SMS transacional – especificação (Advanced API)

Cuidado

É estritamente proibido utilizar SMS transacionais para fins promocionais/de marketing. Devem ser utilizadas apenas para fins de notificação - como notificação SMS.

Nota

Se pretender utilizar uma rota transacional para enviar uma mensagem de notificação em massa, contacte o nosso suporte. Por motivo justificado, podemos permitir esta opção.

URL da API

URL utilizado para enviar os pedidos HTTP:

https://portal.bulkgate.com/api/2.0/advanced/transactional

Nota

Se o pedido não chegar ao destino, repita-o no servidor de reserva backup1.bulkgate.com.

Métodos HTTP suportados

POST - application/json

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Tabela de parâmetros

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
application_id	Identificador da aplicação	Sim	-
application_token	Token de autenticação da aplicação	Sim	-
number	Número do destinatário ou array de números de destinatários - Valor number	Sim ou `admin`	-
admin	Número do administrador BulkGate que recebe a notificação. Mais informações	Sim ou `number`	-
text	Texto da mensagem SMS (máx. 612 caracteres, ou 268 caracteres se for utilizado Unicode), codificação UTF-8. É possível adicionar ao modelo variáveis do array `variables` (outro parâmetro) `Olá <first_name> <last_name> ....`	Sim	-
variables	Array associativo para adicionar variáveis ao texto, por exemplo: `{"first_name": "John", "last_name": "Doe"}`	Não	`[]`
channel	Canais alternativos. Os canais são tentados em cascata, pela ordem em que os indica no objeto - se não conseguirmos entregar a mensagem pelo primeiro canal, é utilizado o seguinte da lista. O SMS não é acrescentado automaticamente; se o quiser como última alternativa, inclua o objeto `sms` na cascata. Se não for indicado nenhum canal, a mensagem é enviada como SMS.	Não	Objeto SMS
country	Indique os números dos destinatários em formato internacional (com prefixo, p. ex. `420`) ou adicione o código do país no formato ISO 3166-1 alpha-2 (`777777777` + `CZ` = `420777777777`). Consulte o exemplo de pedido com o país. Se for `null`, será utilizado o fuso horário que definiu para completar a informação	Não	`null`
schedule	Agende a data e a hora de envio em unix timestamp ou ISO 8601.	Não	Agora
duplicates_check	Selecione `on` para evitar o envio de mensagens duplicadas para o mesmo número de telefone. As mensagens com o mesmo texto enviadas para o mesmo número serão removidas se o intervalo entre elas for inferior a 5 minutos. Com `off`, nenhum duplicado é removido.	Não	`off`
tag	Etiqueta da mensagem para posterior pesquisa pelo utilizador.	Não	-

Valor `number`

O valor number pode ser indicado da seguinte forma:

Array de números de telefone

[ "420777777777", "420888888888", "420999999999" ]

Canais

O objeto channel determina por que canais e por que ordem a mensagem é enviada. A ordem das chaves no seu pedido é a ordem da cascata e o SMS não é acrescentado automaticamente - consulte Cascata de canais.

CHAVE	OBJETO DO CANAL
`sms`	SMS
`viber`	Viber – transacional
`rcs`	RCS
`whatsapp`	WhatsApp

Exemplo de pedido

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "example text <first_name>", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } }

Resposta

Em caso de sucesso:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } }

Em que:

part_ID é o array de ID das partes da mensagem longa original, que foi dividida por exceder o limite de 160 caracteres de uma única mensagem. Mais informações aqui.

Em caso de erro:

{ "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null }

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Em que:

type e error (descrição do erro) encontram-se na tabela de tipos de erros
code representa o código de erro HTTP
detail contém informações adicionais sobre o erro

Consulte todos os tipos de erros da Simple API e da Advanced API aqui.

Esta página foi útil?

Perguntar à IA Copiado