SMS promocional – especificação (Advanced API 1.0)

URL da API

URL utilizado para enviar pedidos HTTP:

https://portal.bulkgate.com/api/1.0/advanced/promotional

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/1.0/advanced/promotional 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	Application ID	Sim	-
application_token	Application token	Sim	-
number	Array de destinatários - Valor number	Sim ou `admins` ou `groups`	-
groups	Array de números de grupos na agenda de contactos BulkGate. Mais informações	Sim ou `number` ou `admins`	-
admins	Array de números de administradores BulkGate que recebem notificações. Mais informações	Sim ou `number` ou `groups`	-
text	Texto da mensagem SMS (máx. 612 caracteres, ou 268 caracteres se o Unicode estiver ativado), codificação UTF-8	Sim, se `number` for indicado como array de números ou se for utilizado o parâmetro `groups` ou `admin`	-
unicode	`Yes`/`true`/`1` para SMS Unicode, `no`/`false`/`0` para SMS de 7 bits	Não	`false`
sender_id	ID do remetente, consulte Tipo de ID do remetente	Não	`gSystem`
sender_id_value	Valor do remetente - `gOwn` (p. ex. "420 777 777 777"), `gText` (p. ex. "BulkGate"), `gProfile` (p. ex. "423"), `gMobile` ou `gPush` (KEY)	Não	`null`
country	Indique os números dos destinatários em formato internacional (com o indicativo, p. ex. `420`) ou acrescente o código do país (`775123456` + `CZ` = `420775123456`). Consulte o exemplo de pedido com o país. Se o valor for `null`, a informação é completada com base no fuso horário que definiu	Não	`null`
schedule	Agende a data e a hora de envio em unix timestamp, ou ISO 8601. Consulte os exemplos abaixo	Não	Agora
duplicates_check	Selecione `same_text` para impedir o envio de mensagens duplicadas para o mesmo número de telefone. Com `same_number` impede o envio de uma mensagem com o mesmo texto ou com um texto diferente para o mesmo número. Se for `null`, não são removidos duplicados. Os duplicados são removidos apenas dentro de um único lote, não entre pedidos.	Não	`null`
tag	Etiqueta da mensagem para posterior pesquisa pelo utilizador.	Não	-

Valor `number`

O valor number pode ser indicado de duas formas:

Array de números de telefone

[ "420775123456", "420606123456", "44771447678" ]

Array associativo com o esquema number, text e variables, em que o único parâmetro obrigatório é number. Se number não estiver preenchido, a mensagem é ignorada.

[ {"number": "420775123456", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ]

No modelo do parâmetro text pode inserir variáveis do array variables.

Tipo de ID do remetente `sender_id`

VALOR	SIGNIFICADO
`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 aplicação Mobile Connect
`gOwn`	Número próprio (requer a verificação do número)
`gProfile`	ID do perfil BulkGate
`<int>`	ID do perfil BulkGate

Exemplos de pedidos

Exemplo de um pedido completo:

POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "420775123456", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, <first_name> <last_name>", "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" }

Exemplo de um pedido com os destinatários indicados como array de números e a hora agendada em unix timestamp:

POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420775123456", "420606123456", "44771447678" ], "text": "Hello, <first_name> <last_name>", "schedule": "1526992636" }

Resposta

Em caso de sucesso:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 1, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "sms_id": "idyrcmdd-0", "part_id": [ "idyrcmdd-0_1", "idyrcmdd-0" ], "number": "420775123456", "channel": "sms" }, { "status": "scheduled", "sms_id": "idyrcmdd-1", "part_id": [ "idyrcmdd-1_1", "idyrcmdd-1" ], "number": "420606123456", "channel": "sms" }, { "status": "invalid_number", "code": 400, "error": "Invalid phone number", "detail": null, "number": "44771447678", "channel": "sms" } ] } }

Em que:

part_ID é o array de IDs das partes da mensagem longa original que foi dividida por não cumprir 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 erro HTTP
detail contém informações adicionais sobre o erro

Todos os tipos de erros da Simple API e da Advanced API podem ser consultados aqui.

Esta página foi útil?

Perguntar à IA Copiado