Cada mensagem enviada através do BulkGate recebe o seu próprio `ID da mensagem`. É o único valor que nos permite rastrear uma mensagem concreta — no portal, na resposta da API e junto do fornecedor de entrega. Antes chamava-se `SMS ID`; é o mesmo valor, apenas mudou de nome pelo caminho, porque há muito que deixámos de enviar apenas SMS.

## O que é o ID da mensagem

O `ID da mensagem` é um identificador de texto de uma mensagem para um destinatário.

- **O BulkGate atribui-o automaticamente** no momento em que aceita a mensagem. Não o pode escolher nem alterar posteriormente.
- **Abrange uma mensagem para um número.** O envio de uma [campanha](https://www.bulkgate.com/pt/centro-de-ajuda/campanhas/criar-campanha-sms/) para mil números cria mil valores de `ID da mensagem` diferentes, e não um valor partilhado.
- **O seu formato varia** consoante a interface através da qual envia. Trate-o como uma cadeia opaca — não deduza dele a data, o canal nem qualquer outra informação, e nunca tente construí-lo por si.

> [!TIP]
> Se precisar de identificar as mensagens com um valor próprio — um número de encomenda, um ID de cliente — é para isso que serve a `Tag (TAG)`, e não o `ID da mensagem`. A diferença é descrita em [Em que difere dos outros identificadores](#em-que-difere-dos-outros-identificadores).

## Porque se chamava SMS ID

O nome `SMS ID` vem do tempo em que o BulkGate enviava apenas SMS. Hoje o Viber, o WhatsApp e o RCS seguem o mesmo caminho, por isso o identificador chama-se `ID da mensagem` — no portal e nas interfaces mais recentes.

As APIs mais antigas, no entanto, não mudaram o nome do campo, para não quebrar as integrações existentes:

| Onde | Como se chama o campo |
|:--|:--|
| Portal | `ID da mensagem` |
| Simple API, Advanced API versão `1.0` | `sms_id` |
| Advanced API versão `2.0`, Integration API, palavras-passe de utilização única | `message_id` |
| Confirmação de entrega (webhook) | `smsID` |

Em todos os casos trata-se do **mesmo valor**. Assim, se pegar no `sms_id` de uma resposta da Simple API e o procurar no histórico em `ID da mensagem`, encontrará precisamente essa mensagem.

## Onde encontrar o ID no portal

1. No menu, clique em `Relatórios`
2. Clique em `História`
3. Clique na linha da mensagem — o detalhe expande-se
4. O `ID da mensagem` encontra-se no lado direito do detalhe; um clique seleciona o valor completo para que o possa copiar

Também funciona no sentido inverso: quando já tem o `ID da mensagem` e pretende encontrar a mensagem, abra `Filtro` por cima da tabela e cole o valor no campo `ID da mensagem`. O mesmo valor está incluído na exportação do histórico para `CSV`.

O que o histórico mostra e como o filtrar é descrito em [Histórico](https://www.bulkgate.com/pt/centro-de-ajuda/relatorios-e-estatisticas/historico/).

> [!IMPORTANT]
> O texto da mensagem não é guardado no histórico para sempre — os registos mais antigos mostram `Esta mensagem expirou` em vez dele. O `ID da mensagem` e os restantes detalhes mantêm-se.

## Onde encontrar o ID na resposta da API

As interfaces devolvem o `ID da mensagem` diretamente na resposta ao pedido de envio — é o único momento em que o obtém de forma programática, por isso guarde-o nesse passo.

| Interface | Como se chama o campo |
|:--|:--|
| [Simple API](https://www.bulkgate.com/pt/documentacao/simple-api/simple-transactional/) | `sms_id` |
| [Advanced API `1.0`](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional/1.0/) | `sms_id` |
| [Advanced API `2.0`](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional/2.0/) | `message_id` |
| [Integration API](https://www.bulkgate.com/pt/documentacao/integration-api/integration-transactional/) | `message_id` |
| [Palavras-passe de utilização única](https://www.bulkgate.com/pt/documentacao/otp-api/envio-de-codigo-de-utilizacao-unica/) | `message_id` |

Além dele, todas devolvem também um array `part_id` — descrito em [O que é o part_id](#o-que-e-o-part-id).

No envio em massa, a resposta contém um array `response` com um registo separado para cada destinatário. O `ID da mensagem` termina então com o número de ordem da mensagem dentro do lote:

```json
{
    "data": {
        "response": [
            {
                "status": "accepted",
                "message_id": "transactional-64afe5f28ffc2-0",
                "part_id": ["transactional-64afe5f28ffc2-0"],
                "number": "420777777777",
                "channel": "sms"
            },
            {
                "status": "accepted",
                "message_id": "transactional-64afe5f28ffc2-1",
                "part_id": ["transactional-64afe5f28ffc2-1"],
                "number": "420777777778",
                "channel": "sms"
            }
        ]
    }
}
```

## O que é o part_id

Uma SMS longa não é entregue à rede do operador numa só peça — é dividida em várias mensagens separadas, que o telemóvel do destinatário volta a juntar. Cada uma dessas partes tem o seu próprio ID, e o `part_id` é a lista deles. Quando e porque é que uma mensagem é dividida é descrito em [Concatenação de mensagens](https://www.bulkgate.com/pt/centro-de-ajuda/sms/concatenacao-de-mensagens/).

O array segue três regras:

- **O último elemento corresponde sempre ao `ID da mensagem`** — não tem sufixo.
- **As partes anteriores têm o sufixo `_1`, `_2`** e assim por diante, pela ordem em que a mensagem é montada.
- **Uma mensagem que não foi dividida tem um único elemento** no `part_id`, idêntico ao `ID da mensagem`. Isto abrange todas as SMS de uma só parte, bem como todas as mensagens de Viber, WhatsApp e RCS — estas nunca são divididas em partes.

Assim, a resposta para uma SMS dividida em três partes tem este aspeto:

```json
{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1_2",
            "tmpde1bcd4b1d1"
        ],
        "number": "420777777777"
    }
}
```

> [!IMPORTANT]
> Cada parte é cobrada como uma SMS separada. O número de elementos do `part_id` é, portanto, também o número de mensagens que paga — três no exemplo acima, apesar de ter enviado uma.

> [!TIP]
> Para emparelhar respostas e confirmações de entrega basta o `ID da mensagem`. O `part_id` é útil quando pretende saber, no momento do envio, em quantas partes a mensagem foi dividida, sem esperar que isso apareça no histórico.

## Onde encontrar o ID num webhook

A confirmação de entrega chega ao endereço que definiu, e o `ID da mensagem` está no seu parâmetro `smsID`. Utilize-o para emparelhar a confirmação com a mensagem que enviou.

- **Individualmente**, o pedido chega via `GET` com os valores na query string — consulte [Confirmação de entrega](https://www.bulkgate.com/pt/documentacao/administracao-da-api/api-confirmacoes-de-entrega-e-sms-recebidos/).
- **Em massa**, chega um único pedido `POST` com um array de registos em `JSON` — consulte [Confirmação de entrega em massa](https://www.bulkgate.com/pt/documentacao/administracao-da-api/api-confirmacoes-de-entrega-em-massa-e-mensagens-recebidas/).

Onde se define o endereço da confirmação de entrega é descrito em [Webhooks](https://www.bulkgate.com/pt/documentacao/administracao-da-api/webhooks/).

> [!NOTE]
> Uma mensagem pode desencadear várias confirmações com o mesmo `smsID` — o estado `2` significa que a mensagem está em fila no operador e que o resultado chegará mais tarde. Conte com ver o mesmo valor mais do que uma vez.

> [!WARNING]
> As mensagens recebidas e as respostas, que reconhece pelo `status` com o valor `10`, não têm o parâmetro `smsID`. Não são uma confirmação de uma mensagem que enviou, mas sim uma nova mensagem do destinatário.

## Para que serve o ID da mensagem

- **Comunicar um problema de entrega.** Sem o `ID da mensagem` não conseguimos rastrear uma mensagem concreta junto do fornecedor de entrega. Todo o procedimento é descrito em [A mensagem não foi entregue](https://www.bulkgate.com/pt/centro-de-ajuda/informacoes-gerais/mensagem-nao-entregue/) — pode anexar até três valores de `ID da mensagem` diferentes a uma comunicação.
- **Emparelhamento no seu próprio sistema.** Guarde o `ID da mensagem` da resposta da API junto da encomenda ou do cliente, e faça corresponder a eles as confirmações de entrega recebidas através do parâmetro `smsID`.
- **Encontrar uma mensagem no histórico.** O `ID da mensagem` é o único filtro que leva exatamente a uma mensagem; por número ou campanha encontrará várias.

## Em que difere dos outros identificadores

O detalhe da mensagem no histórico mostra outros identificadores ao lado do `ID da mensagem`. É fácil confundi-los, mas cada um responde a uma pergunta diferente:

| Identificador | O que identifica | Quem o define |
|:--|:--|:--|
| `ID da mensagem` | Uma mensagem para um destinatário | BulkGate |
| `ID da campanha` | Uma [campanha](https://www.bulkgate.com/pt/centro-de-ajuda/campanhas/criar-campanha-sms/) inteira, ou seja, todas as mensagens enviadas em conjunto | BulkGate |
| `Tag (TAG)` | Tudo o que identificar por si — uma encomenda, um cliente, uma execução de script | O utilizador |
| `Application ID` | A [aplicação](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tokens-de-api/) a partir da qual a mensagem foi enviada | BulkGate |

> [!TIP]
> A `Tag (TAG)` é o único destes identificadores que define por si. Se a preencher no envio, poderá mais tarde filtrar o histórico por ela sem conhecer nenhum `ID da mensagem` — útil quando precisa de encontrar todas as mensagens que pertencem a uma encomenda.