Enviar SMS
Os envios transacionais de SMS consistem no envio de um SMS para um ou mais destinatários que não pertencem à audiência da organização. Como tal, não dependem de um schema previamente definido para a audiência de contactos.
Estes envios permitem a configuração de webhooks - os Webhooks são endpoints, parametrizados pelo cliente em cada envio transacional de SMS, que serão invocados pela Arpoone para encaminhamento de informação de eventos relativos ao estado de entrega da mensagem;
Existe um limite de 10 Sms por HTTP request à API da Arpoone, parametrizáveis no campo Messages.
Atenção especial deve ser dada ao facto de que o campo To (número de telefone de destino) no payload de SMS transacional deve ser um MSISDN válido com o prefixo do país incluído – por exemplo, se o MSISDN for português, deve começar com 351 (Ex.: 351913462111).
Remetentes (senders)
O remetente (sender) da SMS pode ser numérico ou alfanumérico e é configurado na propriedade From do payload de envio de SMS transacional.
A execução do envio transacional de SMS pressupõe a configuração prévia do remetente utilizado no envio. Esta configuração é efetuada na plataforma Arpoone;
Esta configuração consiste nos seguintes passos:
- Efectuar a criação do remetente na plataforma Arpoone;
- Acedido através de: Fotografia de Perfil → Configurações → Remetentes → Remetentes de SMS;
- Configurar o valor do remetente (que pode ser numérico ou alfanumérico) e anexar um ficheiro comprovativo da legitimidade de utilização do remetente a solicitar;
- Aguardar aprovação por parte da equipa da Arpoone. Será enviado um Email de notificação após a solicitação ser aceite.
Payload
Exemplo de payload de envio de SMS, com webhooks:
{
"organizationId": <uuidv4> (Guid),
"messages":
[
{
"text": <string>,
"to": <string> - MSISDN com prefixo de país,
"from": <string> - sender,
"expirationDateTime": <datetime>,
"smsWebhooks": {
"delivered": {
"url": <string>,
"enabled": <bool>
},
"not_delivered": {
"url": <string>,
"enabled": <bool>
},
"pending": {
"url": <string>,
"enabled": <bool>
},
"customPayload": <string>
}
},
...
]
}
Parametrização
A propriedade Messages do payload é um array, logo, permite o envio de várias SMS a partir de um só pedido HTTP.
Descrição dos campos:
To- destinatário do SMS;Text- conteúdo da mensagem;From- o nome do remetente a ser utilizado no envio, cuja configuração deve ser realizada previamente via plataforma Arpoone;ExpirationDateTime- data-limite, no fuso horário UTC, na qual o SMS é enviado – no caso de haver algum atraso temporário nos envios de SMS por parte da plataforma, se a data atual exceder a configurada nesta propriedade, o SMS não é enviado;SmsWebhooks- endereços URL de destino para notificações de alterações de estado de entrega da SMS (ver página SMS Webhooks). A especificação destes endereços é opcional. É também possível definir o valorcustomPayload, que será remetido de volta nos pedidos de notificação da mensagem (tamanho máximo de 1KB).
Retorno
À semelhança do corpo do pedido do endpoint de envio de SMS, a resposta também contém um array Messages. Existe uma correspondência, por índice, entre cada item do array do pedido e do array de resposta, sendo que nesta última cada objecto contém o resultado do agendamento.
O endpoint de envio de SMS retorna Status Code 200 (HTTP OK) caso não ocorra nenhum erro que inviabilize o processamento do pedido, sendo que a indicação de sucesso/erro para cada mensagem é feita, no corpo da resposta, ao nível de cada item no array Messages, propriedade status.
Para cada item, será indicado o estado de agendamento do mesmo na propriedade status (que reflete se o SMS foi enviado com sucesso ou não), o identificador do SMS (messageId), a contagem de segmentos da SMS (segmentCount) o custo do envio do mesmo (cost, valor descontado do saldo da organização) juntamente do código de país do destinatário e descrição de erro (error, se existir).
Exemplo:
{
"error": null,
"messages": [
{
"status": "SUCCESS",
"messageId": "3f22f963-155b-4853-b8fb-0d1944345321",
"segmentCount": 1,
"encoding": 0,
"cost": {
"amount": 1,
"countryCode": "PT"
},
"error": null
},
...
]
}
Erros
Em situações de erro, a propriedade error dentro de cada item do array ```messages` (na resposta) será populada com um objeto que contém informações sobre o erro ocorrido:
"error":
{
"code": "PARAM_EXCEEDS_MAX_LENGTH",
"param": "DisplayName",
"description": ""
}
A propriedade code especifica que tipo de erro ocorreu sendo que a propriedade param especifica qual o parâmetro do payload de envio de SMS que causou o erro.
A lista completa de códigos de erro pode ser consultada neste link