Solução SMS Personalizada
Integração de uma solução/provedor SMS personalizado como parte da sua API do Operador
O Fast Tracks suporta uma variedade de provedores SMS. Se o seu negócio precisar de um provedor que não faz parte da lista de provedores suportados, então você pode construir esta API.
Serviço SMS do Fast Track
O serviço SMS do Fast Track pode ser configurado para enviar solicitações SMS para os endpoints da API do Operador listados abaixo, o que permite ao Operador gerenciar o provedor SMS. Ele suporta o envio de mensagens e a obtenção do status de entrega. O envio está disponível tanto para solicitações SMS individuais quanto em lote.
Os seguintes endpoints podem ser construídos como parte da sua API do Operador:
⬆️ POST /channels/sms/single
⬆️ POST /channels/sms/batch
O Operador pode então encaminhar essas solicitações para o provedor SMS para processamento e responder com as respectivas respostas.
O formato da API e as respostas precisam ser formatados conforme descrito abaixo
É importante que os dados "meta" descritos abaixo sejam enviados de volta ao Fast Track por meio de Webhook ou Polling para que os dados de conversão possam ser armazenados corretamente. Por favor, consulte os exemplos mostrados e as tabelas abaixo para esclarecimentos adicionais.
Pré-Requisitos
- Avise o Fast Track se alguma limitação de taxa deve ser levada em consideração. (Se você planeja implementar limitação de taxa, entre em contato com o Fast Track antes, para que possamos orientá-lo sobre a implementação suportada)
- Avise o Fast Track se algum máximo de lote deve ser levado em consideração.
- Forneça ao Fast Track quaisquer credenciais específicas para os provedores integrados (se necessário)
- Os formatos SMS suportados são GSM7 & USC2
Enviar SMS (Individual)
Uma solicitação de envio SMS individual conterá os dados de cada SMS individual em solicitações separadas para a API.
Implementação do Endpoint
Implemente o endpoint no formato abaixo para suportar SMS de envio único através da API.
⬆️ POST <operator-api-endpoint-url>/channels/sms/single
Cabeçalho da Solicitação
O cabeçalho da solicitação enviada contém um "X-Api-Key" que é um token necessário para autenticar as chamadas da API no endpoint. Este token precisa ser passado para o Fast Track para fazer essas solicitações.
Esquema do Corpo da Solicitação
Consulte o seguinte exemplo de uma solicitação SMS individual enviada pelo Fast Track. A descrição de cada campo está listada na tabela abaixo.
Propriedades obrigatórias são marcadas com *
| Chave | Tipo | Descrição |
|---|---|---|
activity.id * | integer | Um identificador único do SMS |
activity.brand_id * | integer | O identificador único da marca no Fast Track |
activity.user_id * | string | O identificador único do jogador |
activity.activity_id * | integer | O identificador único da atividade configurada no Fast Track |
activity.action_group_id * | integer | Identificador para o grupo de ação ao qual esta atividade pertence |
activity.trigger_hash * | string | Hash identificando o gatilho que disparou esta atividade |
activity.action_id * | integer | Identificador para a ação específica dentro da atividade |
content * | string | O corpo da mensagem SMS |
recipient * | string | O número de telefone do destinatário no formato E.164 |
sender_name * | string | O nome ou número do remetente exibido para o destinatário |
provider_name * | string | O provedor SMS para rotear a mensagem |
encoding * | string | Codificação de caracteres para a mensagem. Valores: auto | gsm7 | ucs2 |
provider_id | string | Identificador de mensagem específico do provedor opcional |
meta | object | Pares chave-valor personalizados definidos na atividade do CRM Fast Track |
Respostas Esperadas
A API do Operador deve retornar as respostas para cada mensagem SMS individual respectivamente para evitar armazenamento não relacionado de dados SMS.
Bem-sucedida Resposta JSON HTTP 200-299
O "sms_id" será um identificador único gerado pela API do Operador que permite ao Fast Track identificar aquela mensagem SMS específica para atualizar seu status de entrega após ser enviada.
ERRO Resposta JSON não-200
Respostas com erro são tipicamente associadas com códigos de status HTTP 400s ou 500s. A resposta deve conter um campo "error" com uma descrição para mostrar o que deu errado e auxiliar na solução de problemas.
As respostas da API do Operador serão tratadas de forma diferente dependendo da classe do código de status HTTP. A tabela abaixo oferece um resumo de como os status HTTP são tratados separadamente.
| Códigos de Status HTTP | Descrição |
|---|---|
200-299 | Entregue com Sucesso. O Fast Track reconhecerá a mensagem e começará a processar a próxima mensagem na fila. |
400-499 | Não Bem-sucedida. Ao receber este erro, o Fast Track pulará a mensagem SMS. Além disso, enviará seus dados para Ações Falhadas, se o serviço estiver habilitado. |
500 ou qualquer outro código de status que não esteja listado acima | Não Bem-sucedida. O serviço falha e o Fast Track continuará tentando até receber uma resposta 200. |
SMS em Lote
O SMS em lote ajuda a processar uma coleção de SMS em uma solicitação para a API. O número de mensagens dentro da solicitação em lote é limitado por uma quantidade inteira definida na configuração e enviado dentro de um período de tempo configurado, mesmo quando o lote ainda não está cheio.
Implementação do Endpoint
Implemente o endpoint no formato abaixo para suportar SMS de envio em lote através da API.
⬆️ POST <operator-api-endpoint-url>/channels/sms/batch
Cabeçalho da Solicitação
O cabeçalho da solicitação enviada contém um "X-Api-Key" que é um token necessário para autenticar as chamadas da API no endpoint. Este token precisa ser passado para o Fast Track para fazer essas solicitações.
Esquema do Corpo da Solicitação
Aqui está um exemplo do formato esperado ao agrupar as solicitações em lote. É similar à solicitação SMS Individual, mas as solicitações são armazenadas em um array, uma após a outra.
Veja a tabela acima (para SMS Individual) para mais detalhes sobre formatação, descrições e campos obrigatórios.
Respostas Esperadas
As respostas abaixo devem ser retornadas pela API do Operador.
Bem-sucedida Resposta JSON HTTP 200
O "activity.id" inicialmente enviado na solicitação será retornado na resposta como "id". Isso é necessário para ajudar o Fast Track a identificar a mensagem SMS individual na solicitação em lote inicial.
O "sms_id" será um identificador único gerado pela API do Operador, que o Fast Track usará para identificar a mensagem SMS relacionada ao atualizar seu status.
Se alguma das categorias listadas ("successful", "failed" ou "fatal") não tiver um SMS associado, elas devem ser retornadas como um array vazio.
A solicitação precisa incluir uma das propriedades successful, failed ou fatal
O fluxo lógico de como a resposta será tratada é muito similar a como os códigos de status HTTP são tratados no SMS Individual. A única diferença é que a resposta com código de status 200 será tratada em vez disso, de acordo com a categoria da mensagem na resposta.
| Categoria da Resposta | Descrição |
|---|---|
successful | Entregue com Sucesso. O Fast Track reconhecerá a mensagem e começará a processar o próximo lote na fila. |
failed | Não Bem-sucedida. Ao receber este erro, o Fast Track pulará a mensagem SMS. Além disso, enviará seus dados para Ações Falhadas, se o serviço estiver habilitado. |
fatal | As mensagens serão tentadas novamente |
Quaisquer outras mensagens que não estejam listadas na resposta serão tentadas novamente.