SMS promocional – especificação (Advanced API)

URL da API

URL utilizado para enviar pedidos HTTP:

https://portal.bulkgate.com/api/2.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/2.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`	-
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 o indicativo, p. ex. `420`) ou acrescente o código do país (`777777777` + `CZ` = `420777777777`). 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

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

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": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ]

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

Canais

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

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

Exemplos de pedidos

Exemplo de um pedido completo:

POST /api/2.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": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ], "groups": [1, 2], "admins": [1, 4], "text": "RCS: o futuro das mensagens móveis para empresas", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "Lt. Hagan", "expiration": 100, "button": { "caption": "Ir para o BulkGate", "url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/" }, "image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg", "text": "*RCS: o futuro das mensagens móveis para empresas*\n\nJá desejou poder enviar mais do que simples texto numa SMS, como uma imagem em alta resolução ou um botão interativo? Ou gostaria de receber uma confirmação de leitura para ter a certeza de que a sua mensagem chegou ao destino? O Rich Communication Services (RCS) veio revolucionar a forma como as empresas comunicam, melhorando a experiência de envio de mensagens e ultrapassando estas limitações." }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true, "text": "RCS: o futuro das mensagens móveis para empresas" } } }

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

POST /api/2.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": [ "420777777777", "420888888888", "420999999999" ], "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":"420777777777", "channel":"sms" }, { "status":"scheduled", "sms_id":"idyrcmdd-1", "part_id":[ "idyrcmdd-1_1", "idyrcmdd-1" ], "number":"420888888888", "channel":"sms" }, { "status":"invalid_number", "code":400, "error":"Invalid phone number", "detail":null, "number":"420999999999", "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