Mensagens transacionais em massa – especificação

URL da API

URL utilizado para enviar pedidos HTTP:

https://portal.bulkgate.com/api/1.0/integration/transactional-bulk

Nota

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

POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Cuidado

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

Nota

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

Aviso

Os destinatários que cancelaram a subscrição receberão a mensagem (o opt-out aplica-se apenas a mensagens promocionais).

Tabela de parâmetros

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
application_id	Application ID	Sim	-
application_token	Token de autenticação da aplicação	Sim	-
tag	Etiqueta de identificação pessoal	Não	-
messages	Array de mensagens	Sim	Objeto de mensagem

Objeto de mensagem

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
primary_channel	O canal principal a utilizar em primeiro lugar na cascata	Não	`sms`
phone_number	Número de telefone do destinatário	Sim	-
country	Indique os números dos destinatários em formato internacional (com indicativo, por exemplo `420`) ou acrescente o código do país (`775123456` + `CZ` = `420775123456`). Veja um exemplo do requisito de um país. Se o valor for `null`, é utilizado o fuso horário definido para completar a informação	Não	`null`
schedule	Agende a data e a hora de envio em unix timestamp. Veja os exemplos abaixo.	Não	`null`
channels	Array associativo de objetos de canal	Sim	Objeto de canal

Objeto do canal Viber

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender	Nome do remetente	Não	-
expiration	Tempo após o qual a mensagem expira	Não	`3600`
text	Texto da mensagem. É possível acrescentar ao modelo variáveis do array `variables` (outro parâmetro) `Olá <first_name> <last_name> ....`	Sim	-
variables	Array associativo para acrescentar variáveis ao texto, por exemplo `{"first_name": "John", "last_name": "Doe"}`	Não	`[]`

Objeto do canal SMS

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender_id	ID do remetente, consulte Tipo de ID do remetente	Não	`gSystem`
sender_id_value	Valor do remetente - `gOwn` (por exemplo, "420 777 777 777"), `gText` (por exemplo, "BulkGate"), `gProfile` (por exemplo, "423"), `gMobile` ou `gPush` (KEY)	Não	`''`
unicode	`Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits	Não	`false`
text	Texto do SMS (máx. 612 caracteres ou 268 caracteres se o Unicode estiver ativado), codificação UTF-8. É possível acrescentar ao modelo variáveis do array `variables` (parâmetro adicional) `Olá <first_name> <last_name> ....`	Sim	-
variables	Array associativo para acrescentar variáveis ao texto, por exemplo: `{"first_name": "John", "last_name": "Doe"}`	Não	`[]`

Tipo de ID do remetente `sender_id`

VALOR	DESCRIÇÃO
`gSystem`	Número do sistema
`gShort`	Short code
`gText`	Remetente de texto
`gMobile`	Mobile Connect
`gPush`	Mobile Connect push - Envia uma notificação para a sua aplicação Mobile Connect
`gOwn`	Número próprio (requer verificação do número)
`gProfile`	ID do perfil de remetente
`<int>`	ID do perfil de remetente

Exemplo de um pedido completo:

POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } } ] }

A resposta a este comando pode ser:

Em caso de sucesso

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

Em caso de erro:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } }

{ "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 erro
code representa o erro HTTP
detail é uma informação adicional sobre o erro

Todos os tipos de erro da Simple API e da Advanced API encontram-se aqui.

Esta página foi útil?

Perguntar à IA Copiado