ID da mensagem (antes SMS ID)

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 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.

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:

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.

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.

Além dele, todas devolvem também um array part_id — descrito em O que é 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:

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.

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:

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.
• Em massa, chega um único pedido POST com um array de registos em JSON — consulte Confirmação de entrega em massa.

Onde se define o endereço da confirmação de entrega é descrito em Webhooks.

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 — 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: