API SMS

Com a plataforma Contact Center AI (CCAI), é possível usar a API SMS para processar mensagens SMS recebidas e enviadas.

Autenticação

Para usar a API SMS, você precisa de uma credencial.

Para criar uma credencial para a API SMS, siga estas etapas:

  1. No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor > Gerenciamento de credenciais da API.

  2. Clique no botão + Adicionar credencial de API. Uma mensagem Adicionar credencial de API será aberta.

  3. Digite um Nome para a credencial.

  4. Clique em Criar.

API SMS de saída

A API Outbound SMS fornece um endpoint para iniciar mensagens SMS de saída. Isso permite enviar mensagens SMS de forma programática para consumidores.

Há três pontos principais a serem considerados ao usar essa API:

  • Esse serviço não foi projetado para enviar dezenas de milhares de mensagens de uma só vez. O objetivo é a troca de mensagens orientada a eventos.

  • Os consumidores podem responder à mensagem SMS e iniciar uma sessão de suporte.

  • Essa API não funciona se você precisar enviar várias mensagens SMS para o mesmo número no mesmo dia.

Casos de uso

Os exemplos de casos de uso da API SMS de saída são baseados em eventos. Por exemplo, se você quiser notificar o consumidor de que o pedido está pronto para retirada E dar a opção de responder. Uma sessão ativa é criada quando um SMS de saída é enviado. Quando o cliente responde, ele é encaminhado para um agente.

A diferença entre essa API e a API de SMS de saída sem sessão é que, com a API sem sessão, você só envia a notificação. Se o consumidor responder, ele vai receber uma mensagem padrão (se configurada) e não será encaminhado para um agente.

Outros possíveis casos de uso:

  • Login da conta.
  • Atividade da conta.
  • Eventos importantes de uso da conta.
  • Detecção de problemas em dispositivos conectados.
  • Notificações de ETA para serviços sob demanda, como entregas e caronas.
  • Lembretes de agendamento.
  • Alertas proativos de serviço ou conta.
  • Autenticação de dois fatores (exige que o cliente tenha um gerador de códigos e um processo de serviço).

Endpoint de API de SMS de saída

O URI base para esse novo endpoint é:

POST https://<subdomain>.<domain>/apps/api/v1/sms

Suporte a SMS recebidos

Se um ambiente quiser oferecer suporte a respostas de SMS recebidas, o número de envio também precisará ser configurado como um número de SMS recebido atribuído a uma fila. Cada número de telefone para SMS só pode ser atribuído a uma fila. Para mais informações, consulte: Configuração geral do chat por SMS.

Se um usuário final responder a um SMS configurado dessa forma, ele será direcionado ao menu da fila de SMS a que o número de telefone de SMS de entrada está atribuído. Para mais informações, consulte Configurações de chat de mensagens SMS: número de telefone.

Operações de API

Esta seção descreve as operações de API, os parâmetros de corpo e os códigos de resposta.

Corpo e parâmetros

Os seguintes campos precisam ser incluídos no corpo da solicitação de API:

Nome do campo Tipo Obrigatório Descrição Valores Observações
agent_id Número inteiro Não O agente correspondente a esse ID será atribuído a uma nova conversa se não houver uma entre os números fornecidos. Se o agente estiver conectado a um chat, a mensagem será enviada em nome dele.
agent_email String Não O endereço de e-mail do agente.
chat_type String Sim Mensagem SMS SMSAP
chat_subtype String Sim api_initiated
end_user_number String Sim Número de telefone para onde a mensagem de texto será enviada Validação: número de telefone válido: +18882468888 para um número de telefone dos EUA
outbound_number String Sim Número de telefone de saída a ser usado para enviar a mensagem SMS. Validação: a) o número de telefone precisa ser um número de telefone de SMS associado ao locatário, b) número de telefone ausente, c) o número de telefone está no formato incorreto: +18882468888 para um número de telefone dos EUA
mensagem String Sim Mensagem SMS a ser enviada ao consumidor Mensagens longas: divida mensagens longas em várias mensagens (isso deve ser abordado na capacidade de SMS de saída atual). Validação: a) mensagem ausente, b) a mensagem excede o número máximo de caracteres (em x)
ticket_id ID Não Associa a sessão a um ID de tíquete de CRM específico. Observação: IDs de ingressos inválidos serão ignorados.

Erro e sucesso

Caso Resultado esperado Copiar
O serviço de SMS está ativado
O serviço de SMS de saída está ativado
O valor de chat_type é "OutboundSMSAPI"
O end_user_number é fornecido e bem formatado
O outbound_number é fornecido e bem formatado
Para números de telefone que não são dos EUA: o número de telefone que não é dos EUA está ativado
A mensagem é fornecida
Não há um chat ativo entre outbound_number e end_user_number		 sucesso (200) Exemplo de resposta de sucesso
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
O ID e o e-mail do agente são fornecidos erro Apenas um de agent_id ou agent_email pode ser fornecido.
O ID ou e-mail do agente foi fornecido
O agente não está conectado a um chat em andamento		 erro Falha no envio de SMS. O representante não está conectado ao chat.
O serviço de SMS não está ativado erro "O serviço de SMS não está ativado".
O serviço de SMS de saída não está ativado erro "O serviço de SMS de saída não está ativado"
chat_type não foi fornecido erro "chat_type needs to be provided"
chat_type é fornecido, mas não está definido como "sms" erro "É necessário fornecer um chat_type válido"
end_user_number foi fornecido, mas não está bem formatado erro "end_user_number is invalid"
(observação: número de telefone válido: "+18882468888" para um número de telefone dos EUA)
end_user_number não foi fornecido erro "end_user_number is required"
outbound_number é fornecido, mas não está bem formatado erro "outbound_number is invalid"
(observação: número de telefone válido: "+18882468888" para um número de telefone dos EUA)
outbound_number é fornecido, mas não existe para esse locatário erro "outbound_number is not found"
outbound_number não foi fornecido erro "outbound_number is required"
outbound_number é um número de telefone de fora dos EUA e o "serviço de número de telefone de fora dos EUA" não está ativado erro "O serviço de número de telefone fora dos EUA não está ativado"
Observação:depende da configuração Número de telefone fora dos EUA em Configurações > SMS durante a chamada > Configurações de número de telefone fora dos EUA
A mensagem está vazia erro "message is required"
Chat ativo entre outbound_number e end_user_number erro "Falha no envio de SMS. O consumidor já está em uma sessão de SMS ativa."
ticket_id is filled but does not exist in CRM erro "A passagem não foi encontrada"

Validade do SMS

As mensagens SMS enviadas ficam ativas assim que são enviadas.

Qualquer conversa por SMS precisa ser encerrada antes que uma nova sessão possa ser estabelecida entre um número de telefone de saída e um do consumidor. Isso inclui mensagens SMS de saída enviadas usando a API. O envio de SMS vai falhar se houver um chat ativo entre os números de telefone de saída e do consumidor.

Opções de tempo limite automático do chat

As opções de tempo limite automático do chat são configuradas em Configurações > Chat > Expiração de SMS e tempo limite global. Isso fornece controles sobre por quanto tempo uma sessão de chat vai permanecer ativa se não houver atividade ou progresso no fluxo da sessão.

Distinções de status no chat

Confira a seguir as distinções entre as mudanças de estado do processo de chat:

  • Estado de seleção da fila Expiração do chat: os chats enviados usando a API são considerados no estado de seleção da fila até que o consumidor responda

    Qualquer sessão de chat que não tenha avançado além do estado de seleção de fila. Isso inclui mensagens SMS enviadas para fora que não foram respondidas por um consumidor. É possível definir por quanto tempo um chat pode permanecer nesse estado antes de expirar (mensagem enviada e o consumidor não responde dentro do tempo limite - o chat expira).

  • Expiração de chat por SMS sem resposta (durante o horário de atendimento): o período em que um chat pode ficar sem resposta em uma fila antes de expirar dentro do horário de atendimento definido para a fila específica.

  • Expiração de chat por SMS não atendido (durante o horário de folga): o período em que um chat pode ficar sem resposta em uma fila antes de expirar fora do horário de funcionamento definido para a fila específica.

  • Tempo limite do chat por SMS de saída: as sessões de chat por SMS de saída expiram automaticamente se não houver atividade por [x] minutos.

Detalhes do status no chat

  • Quando um SMS de saída é enviado usando a API, a conversa é considerada ativa, mas não conectada.

  • Essas conversas por SMS ativas são consideradas no estado de seleção de fila até que o consumidor responda.

  • As conversas são consideradas conectadas quando o consumidor responde e um agente é atribuído a ela.

Impacto do status no chat nos timers aplicados

  • Os chats ativos enviados usando a API que não receberam uma resposta do consumidor estão sujeitos ao timer de seleção de estado da fila.

  • As conversas conectadas a um agente estão sujeitas ao timer de expiração de saída.

  • Se um consumidor responder à mensagem inicial, mas um agente nunca for atribuído, o chat não será conectado e estará sujeito ao timer de expiração de chat sem resposta, dentro ou após o horário de funcionamento.

Exemplo de fluxo e status de mensagens da API:

  1. A mensagem SMS é enviada usando a API para o consumidor. O chat está no estado selecionando fila e não está conectado a um agente.

  2. O timer de expiração do chat no estado de seleção da fila é iniciado. O chat expira e é encerrado se o consumidor não responder dentro do limite do timer.

  3. O consumidor responde ao chat, que agora está conectado a um agente.

  4. O consumidor envia a última mensagem. O timer de tempo limite do chat por SMS de saída começa.

  5. O tempo limite do timer de chat por SMS de saída foi atingido. O chat foi encerrado.

Nenhum timer de dispensa de chat: para sessões de SMS de saída iniciadas por API, o timer de dispensa de chat não funciona. Portanto, um evento de dispensa de chat não ocorre mesmo depois que o chat chega como uma conversa de entrada quando um consumidor responde à mensagem.

Definição de resposta

A API responde com um único objeto de chamada, como visto no modelo de /calls.

API SMS de saída sem sessão

A plataforma CCAI oferece uma API de SMS de saída que pode oferecer suporte a mensagens de SMS de saída sem sessões vinculadas.

Essa chamada de API inicia mensagens SMS não vinculadas a sessões que podem ser acionadas durante um fluxo de trabalho atual usando a plataforma de IA de conversa (CCAI Platform).

Um SMS sem sessão é preferível em casos em que apenas uma mensagem única é enviada aos consumidores e não há necessidade de abrir um tíquete de CRM.

Com essa API, é possível enviar até 500 mensagens por chamada de API.

Casos de uso

Os casos de uso comuns de um SMS sem sessão podem incluir o seguinte:

  • Configuração de senha única.

  • Código de verificação.

  • Lembretes de agendamento.

  • Links de feedback.

  • Mensagens de marketing ou promocionais.

A API sem sessão de saída e a API de SMS de saída variam porque, com a API de SMS de saída, quando um consumidor responde, uma sessão ativa é iniciada e ele pode ser encaminhado para um agente. Embora compartilhem casos de uso semelhantes (notificações de entrega, lembretes de consultas), a diferença está no que acontece quando o consumidor responde. Eles podem receber uma notificação padrão de não responder sem sessão, mas com SMS de saída, serão encaminhados para um agente.

Endpoint de API SMS de saída sem sessão

O URI base para este endpoint é:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

Adicionar uma credencial de API

  1. No portal da plataforma CCAI, acesse Configurações > Configurações do desenvolvedor > Gerenciamento de credenciais da API.

  2. Clique no botão + Adicionar credencial de API. Uma mensagem Adicionar credencial de API será aberta.

  3. Insira um nome para a credencial Name.

  4. Clique em Criar.

Como enviar mensagens SMS

Para enviar um SMS de saída sem sessão, chame POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms e transmita os seguintes parâmetros de solicitação:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Nome do campo Tipo Obrigatório Descrição Observações
from_phone String Sim O número de telefone de onde as mensagens serão enviadas. Precisa ser um número válido dos EUA.
A chamada de API vai retornar um erro se:
* o número de telefone não for um número de telefone de SMS associado ao locatário
* o campo "from_phone" estiver vazio
* o número de telefone não seguir o formato correto. Por exemplo, o número a seguir é um número de telefone válido dos EUA: +18882468888
to_phones Matriz [String] Sim Os números de telefone para os quais as mensagens serão enviadas. Para garantir que a chamada de API seja bem-sucedida, faça o seguinte:
* Confirme se você tem um número de telefone válido, como +18882468888
O número máximo de telefones é 100 por chamada de API.
mensagens Matriz [String] Sim As mensagens a serem enviadas. O número máximo de mensagens separadas que você pode enviar é cinco.
Cada mensagem tem um limite de 320 caracteres, que não pode ser excedido.

Respostas da API

Se a chamada de API for bem-sucedida, você verá:

  • code: 200

  • ID da solicitação

    Registre o ID da solicitação nos registros do sistema. Se você precisar resolver um problema, o suporte vai precisar do ID da solicitação para ajudar.

Se a chamada de API falhar, você vai ver:

  • code: 4xx

  • Mensagem de erro

Limitações de SMS

  • A API processa um máximo de 300 mensagens por minuto.

  • Todas as mensagens não processadas vão expirar em duas horas.