API de SMS

Con Contact Center AI Platform (CCAI Platform), puedes usar la API de SMS para controlar los mensajes SMS entrantes y salientes.

Autenticación

Para usar la API de SMS, necesitas una credencial.

Para crear una credencial para la API de SMS, sigue estos pasos:

  1. En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador > Administración de credenciales de API.

  2. Haz clic en el botón + Add API Credential. Se abrirá un mensaje de Add API Credential.

  3. Ingresa un Nombre para la credencial.

  4. Haz clic en Crear.

API de SMS salientes

La API de SMS salientes proporciona un extremo para iniciar mensajes de SMS salientes. Esto te permite enviar mensajes de SMS a los consumidores de forma programática.

Hay tres puntos clave que debes tener en cuenta cuando uses esta API:

  • Este servicio no está diseñado para enviar decenas de miles de mensajes a la vez. El objetivo es la mensajería controlada por eventos.

  • Los consumidores pueden responder el mensaje SMS y comenzar una sesión de asistencia.

  • Esta API no funcionará si necesitas enviar varios mensajes SMS al mismo número en el mismo día.

Casos de uso

Los casos de uso de ejemplo de la API de SMS salientes se basan en eventos. Por ejemplo, si deseas notificar al consumidor que su pedido está listo para retiro Y darle la opción de responder. Se crea una sesión activa cuando se envía un SMS saliente. Cuando el cliente responde, se lo dirige a un agente.

La diferencia entre esta API y la de SMS saliente sin sesión es que, con la opción sin sesión, solo envías la notificación y, si el consumidor responde, recibe un mensaje predeterminado (si lo configuras) y no se lo enruta a un agente.

Otros posibles casos de uso:

  • Acceso a la cuenta
  • Actividad de la cuenta
  • Son eventos importantes de uso de la cuenta.
  • Detección de problemas del dispositivo conectado
  • Notificaciones de ETA para servicios a pedido, como entregas y viajes compartidos
  • Recordatorios de citas
  • Alertas proactivas sobre el servicio o la cuenta
  • Autenticación de dos factores (requiere que el cliente tenga un generador de códigos y un proceso de servicio existentes).

Extremo de API de SMS salientes

El URI base para este nuevo extremo es el siguiente:

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

Compatibilidad con SMS entrantes

Si un entorno desea admitir respuestas de SMS entrantes, el número saliente también debe configurarse como un número de SMS entrante asignado a una cola. Cada número de teléfono para SMS solo se puede asignar a una cola. Para obtener más información, consulta Configuración general del chat por SMS.

Si un usuario final responde a un SMS configurado de esta manera, se lo dirigirá al menú de la cola de SMS al que está asignado el número de teléfono del SMS entrante. Para obtener más información, consulta Configuración del chat de mensajería SMS: número de teléfono.

Operaciones de la API

En esta sección, se describen las operaciones de la API, los parámetros del cuerpo y los códigos de respuesta.

Body y Params

Los siguientes campos deben incluirse en el cuerpo de la solicitud de la API:

Nombre del campo Tipo Obligatorio Descripción Valores Notas
agent_id Número entero No El agente correspondiente a este ID se asignará a un chat nuevo si no existe un chat entre los números proporcionados. Si el agente está conectado a un chat existente, el mensaje se enviará en su nombre.
agent_email String No Es la dirección de correo electrónico del agente.
chat_type String Sí Mensaje SMS SMSAP
chat_subtype String Sí api_initiated
end_user_number String Sí Número al que se enviará el mensaje de texto Validación: Número de teléfono válido: +18882468888 para un número de teléfono de EE.UU.
outbound_number String Sí Número de teléfono saliente que se usará para enviar el mensaje SMS Validación: a) El número de teléfono debe ser un número de teléfono para SMS asociado al arrendatario, b) Falta el número de teléfono, c) El número de teléfono tiene un formato incorrecto: +18882468888 para un número de teléfono de EE.UU.
mensaje String Sí Mensaje SMS que se enviará al consumidor Mensajes largos: Divide los mensajes largos en varios mensajes (esto debería estar cubierto en la capacidad existente de SMS salientes). Validación: a) Falta el mensaje, b) El mensaje supera la cantidad máxima de caracteres (por X)
ticket_id id No Asociará la sesión a un ID de ticket de CRM específico Nota: Se ignorarán los IDs de tickets no válidos.

Error y éxito

Caso Resultado esperado Copiar
El servicio de SMS está habilitado
El servicio de SMS salientes está habilitado
El valor de chat_type es "OutboundSMSAPI"
Se proporciona end_user_number y tiene el formato correcto
Se proporciona outbound_number y tiene el formato correcto
Para números de teléfono que no son de EE.UU.: El número de teléfono que no es de EE.UU. está habilitado
Se proporciona el mensaje
No hay un chat activo entre outbound_number y end_user_number		 correcto Muestra de respuesta exitosa (200)
{ 
  "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"
}
Se proporcionan el ID y el correo electrónico del agente error Solo se puede proporcionar uno de los campos agent_id o agent_email.
Se proporcionó el ID o el correo electrónico del agente.
El agente no está conectado a un chat existente.		 error No se pudo enviar el SMS saliente. El agente no está conectado al chat.
El servicio de SMS no está habilitado error "El servicio de SMS no está habilitado".
El servicio de SMS salientes no está habilitado error "El servicio de SMS salientes no está habilitado"
No se proporciona chat_type error "Se debe proporcionar chat_type"
Se proporciona chat_type, pero no se establece en "sms". error "Se debe proporcionar un chat_type válido"
Se proporcionó end_user_number, pero no tiene el formato adecuado error "end_user_number no es válido"
(nota: número de teléfono válido: "+18882468888" para un número de teléfono de EE.UU.)
No se proporciona end_user_number error "Se requiere end_user_number"
Se proporcionó outbound_number, pero no tiene el formato adecuado error "outbound_number is invalid"
(nota: número de teléfono válido: "+18882468888" para un número de teléfono de EE.UU.)
Se proporcionó outbound_number, pero no existe para ese arrendatario. error "No se encontró outbound_number"
No se proporciona outbound_number error "Se requiere outbound_number"
outbound_number es un número de teléfono que no es de EE.UU. y no está habilitado el "servicio de número de teléfono que no es de EE.UU." error "Non US phone number service is not enabled"
Nota: Depende del parámetro de configuración Non-US phone number en Settings > In Call SMS > Non-US Phone Number Configurations
El mensaje está vacío error "Se requiere un mensaje"
Chat activo entre outbound_number y end_user_number error "No se pudo enviar el SMS saliente. El consumidor ya está en una sesión de SMS activa".
ticket_id está completo, pero no existe en el CRM error "No se encontró el ticket"

Vencimiento de SMS

Los mensajes SMS salientes están activos apenas se envían.

Cualquier chat por SMS debe finalizar antes de que se pueda establecer una nueva sesión de chat por SMS entre un número de teléfono saliente y uno del consumidor determinados. Esto incluye los mensajes SMS salientes enviados a través de la API. Cualquier SMS saliente fallará si existe un chat activo entre los números de teléfono del comercio y del consumidor.

Opciones de tiempo de espera automático del chat

Las opciones de tiempo de espera automático del chat se configuran en Configuración > Chat > Vencimiento de SMS y tiempo de espera global. Esto proporciona controles sobre cuánto tiempo permanecerá activa una sesión de chat si no hay actividad o progreso en el flujo de la sesión de chat.

Distinciones del estado del chat

A continuación, se indican las diferencias entre los cambios de estado del proceso de chat:

  • Vencimiento del chat en estado de selección de colaLos chats salientes enviados a través de la API se consideran en estado de selección de cola hasta que el consumidor responde

    Cualquier sesión de chat que no haya avanzado más allá del estado de selección de la fila. Esto incluye los mensajes de SMS salientes enviados a los que un consumidor no respondió. Es posible definir cuánto tiempo puede permanecer un chat en este estado antes de que venza (se envía un mensaje y el cliente no responde dentro del temporizador, por lo que el chat vence).

  • Vencimiento del chat por SMS sin responder (durante el horario de atención): Es el período durante el cual un chat puede permanecer sin responder en una cola antes de que venza dentro del horario de atención establecido para la cola específica.

  • Vencimiento de chats por SMS sin responder (fuera del horario de atención): Es el período durante el cual un chat puede permanecer sin responder en una cola antes de vencer fuera del horario de atención establecido para la cola específica.

  • Tiempo de espera de chat por SMS saliente Las sesiones de chat por SMS saliente vencerán automáticamente si no hay actividad durante [x] minutos.

Detalles del estado del chat

  • Cuando se envía un SMS saliente con la API, el chat se considera activo, pero no conectado.

  • Estos chats de SMS salientes activos se consideran en el estado de selección de cola hasta que el cliente responde.

  • Los chats se consideran conectados una vez que el cliente responde y se asigna un agente al chat.

Impacto del estado del chat en los temporizadores aplicados

  • Los chats activos enviados a través de la API que no recibieron una respuesta del consumidor están sujetos al temporizador del estado de selección de la fila.

  • Los chats conectados a un agente están sujetos al temporizador de vencimiento de salida.

  • Si un consumidor responde al mensaje inicial, pero nunca se asigna un agente, el chat no se conecta y está sujeto al temporizador de vencimiento de chat sin respuesta, dentro o después del horario de atención.

Ejemplo de flujo y estados de mensajes de la API:

  1. Se envía un mensaje SMS al consumidor a través de la API. El chat está en estado de selección de la fila y no está conectado a un agente.

  2. Se inicia el temporizador de vencimiento del chat del estado de selección de la fila. El chat se agota y finaliza si el consumidor no responde dentro del umbral del temporizador.

  3. El cliente responde al chat, que ahora está conectado a un agente.

  4. El cliente envía el último mensaje. Se inicia el temporizador de tiempo de espera del chat por SMS saliente.

  5. Se alcanzó el umbral del temporizador de tiempo de espera de chat por SMS saliente. Finalizó el chat.

Sin temporizador de descarte de chat: En el caso de las sesiones de SMS salientes iniciadas por la API, el temporizador de descarte de chat no funciona, por lo que no se producirá un evento de descarte de chat, incluso después de que ese chat llegue como un chat entrante cuando un consumidor responda al mensaje.

Definición de respuesta

La API responde con un solo objeto de llamada, como se ve en el modelo de /calls.

API de SMS salientes sin sesión

La plataforma de CCAI ofrece una API de SMS salientes que puede admitir mensajes SMS salientes sin sesiones vinculadas.

Esta llamada a la API inicia mensajes SMS no vinculados a la sesión que se pueden activar durante un flujo de trabajo existente con CCAI Platform.

Se prefiere un SMS sin sesión en instancias en las que solo se envía un mensaje único a los consumidores y no es necesario abrir un ticket de CRM.

Esta API de SMS salientes permite enviar hasta 500 mensajes por llamada a la API.

Casos de uso

Estos son algunos casos de uso comunes para los SMS sin sesión:

  • Configuración de contraseña de un solo uso

  • Código de verificación

  • Recordatorios de citas

  • Vínculos de comentarios

  • Mensajes promocionales o de marketing

La API de Outbound sin sesión y la API de Outbound SMS varían en que, con la API de Outbound SMS, cuando un consumidor responde, se inicia una sesión activa y se lo puede dirigir a un agente. Si bien comparten casos de uso similares (notificaciones de entrega, recordatorios de citas), la diferencia radica en lo que sucede cuando responde el consumidor. Es posible que reciban una notificación predeterminada de no respuesta sin sesión, pero, con los SMS salientes, se los dirigirá a un agente.

Extremo de API de SMS salientes sin sesión

El URI base para este extremo es el siguiente:

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

Agrega una credencial de API

  1. En el portal de la CCAI Platform, ve a Settings > Developer Settings > API Credential Management.

  2. Haz clic en el botón + Add API Credential. Se abrirá un mensaje de Add API Credential.

  3. Ingresa un nombre para la credencial Nombre.

  4. Haz clic en Crear.

Envío de mensajes SMS

Para enviar un SMS saliente sin sesión, llama a POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms y pasa los siguientes parámetros de solicitud:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Nombre del campo Tipo Obligatorio Descripción Notas
from_phone String Sí Es el número de teléfono desde el que se enviarán los mensajes. Debe ser un número de EE.UU. válido.
La llamada a la API devolverá un error en los siguientes casos:
* El número de teléfono no es un número de teléfono de SMS asociado con el arrendatario.
* El campo from_phone está vacío.
* El número de teléfono no sigue el formato correcto. Por ejemplo, el siguiente número es un número de teléfono válido de EE.UU.: +18882468888
to_phones Array [String] Sí Son los números de teléfono a los que se enviarán los mensajes. Para garantizar que la llamada a la API se realice correctamente, haz lo siguiente:
* Confirma que tienes un número de teléfono válido, como +18882468888.
La cantidad máxima de números de teléfono es de 100 por llamada a la API.
mensajes Array [String] Sí Son los mensajes que se enviarán. La cantidad máxima de mensajes separados que puedes enviar es de 5.
Cada mensaje tiene un límite de 320 caracteres y no puede excederlo.

Respuestas de la API

Si la llamada a la API se realiza correctamente, verás lo siguiente:

  • code: 200

  • ID de solicitud

    Asegúrate de registrar el ID de solicitud en los registros de tu sistema. En caso de que necesites solucionar un problema, el equipo de asistencia necesitará el ID de solicitud para ayudarte.

Si la llamada a la API falla, verás lo siguiente:

  • code: 4xx

  • Mensaje de error

Limitaciones de SMS

  • La API procesa un máximo de 300 mensajes por minuto.

  • Todos los mensajes no procesados vencerán en 2 horas.