Para crear y configurar un buzón de canal API en instalaciones de Chatwoot, sigue el paso descrito a continuación.
Configura el canal API
Paso 1. Ve a Configuración → Buzones → “Agregar Buzón”.
Paso 2. Haz clic en el icono "API".
Paso 3. Proporciona un nombre para el canal y una URL de callback. Aquí tienes un ejemplo:
Paso 4. "Agregar agentes" a tu buzón API.
La configuración del buzón está completa.
Envía mensajes al canal API
Para enviar mensajes al canal API, asegúrate de comprender los siguientes modelos y la nomenclatura utilizada en Chatwoot.
-
Canal: Un canal define el tipo de fuente de las conversaciones. Ej., Facebook, Twitter, API, etc.
-
Buzón: Puedes crear múltiples fuentes de conversaciones del mismo tipo de canal. Ej., Puedes tener más de una página de Facebook conectada a una cuenta de Chatwoot. Cada página se llama buzón en Chatwoot.
-
Conversación: Una conversación es una colección de mensajes.
-
Contacto: Cada conversación tiene una persona real asociada a ella, llamada contacto.
-
Buzones de contacto: Esta es la sesión de cada contacto en un buzón. Un contacto puede tener múltiples sesiones y múltiples conversaciones en el mismo buzón.
¿Cómo enviar un mensaje en un canal API?
Para enviar un mensaje en un canal API, crea un contacto, inicia una conversación y finalmente envía el mensaje.
Las API requieren el api_access_token en el encabezado de la solicitud. Puedes obtener este token visitando tu configuración de Perfil → Token de Acceso.
1. Crear un contacto
Pasa el ID del buzón del canal API junto con los demás parámetros especificados. Esto creará una sesión para ti automáticamente. Una respuesta de ejemplo se vería como la siguiente.
{
"email": "string",
"name": "string",
"phone_number": "string",
"thumbnail": "string",
"additional_attributes": {},
"contact_inboxes": [
{
"source_id": "string",
"inbox": {
"id": 0,
"name": "string",
"website_url": "string",
"channel_type": "string",
"avatar_url": "string",
"widget_color": "string",
"website_token": "string",
"enable_auto_assignment": true,
"web_widget_script": "string",
"welcome_title": "string",
"welcome_tagline": "string",
"greeting_enabled": true,
"greeting_message": "string"
}
}
],
"id": 0,
"availability_status": "string"
}
Como puedes ver en la carga útil, podrás ver los contact_inboxes y cada contact_inbox tendrá un source_id. Source ID puede ser visto como el identificador de sesión. Utilizarás este source_id para crear una nueva conversación como se define a continuación.
2. Crear una conversación
Usa el source_id recibido en la llamada API anterior. Recibirás un ID de conversación que puede ser utilizado para crear un mensaje.
{
"id": 0
}
3. Crear un mensaje nuevo
Hay 2 tipos de mensajes.
-
Entrante: Los mensajes enviados por el usuario final se clasifican como mensajes entrantes.
-
Saliente: Los mensajes enviados por el agente se clasifican como mensajes salientes.
Si llamas a la API con el contenido correcto, recibirás una carga útil similar a esta:
{
"id": 0,
"content": "This is a incoming message from API Channel",
"inbox_id": 0,
"conversation_id": 0,
"message_type": 0,
"content_type": null,
"content_attributes": {},
"created_at": 0,
"private": false,
"sender": {
"id": 0,
"name": "Pranav",
"type": "contact"
}
}
Si todo es exitoso, verás la conversación en el panel como se muestra a continuación.
Serás notificado cuando se cree un nuevo mensaje en la URL especificada al crear el canal API. Puedes leer sobre la carga útil del mensaje aquí.
Recibir mensajes usando URL de callback
Cuando se crea un mensaje nuevo en el canal API, recibirás una solicitud POST en la URL de Callback especificada al crear el canal API. La carga útil sería así.
Encuentra la lista completa de eventos soportados por el webhook aquí.
Tipo de evento: message_created
{
"id": 0,
"content": "This is a incoming message from API Channel",
"created_at": "2020-08-30T15:43:04.000Z",
"message_type": "incoming",
"content_type": null,
"content_attributes": {},
"source_id": null,
"sender": {
"id": 0,
"name": "contact-name",
"avatar": "",
"type": "contact"
},
"inbox": {
"id": 0,
"name": "API Channel"
},
"conversation": {
"additional_attributes": null,
"channel": "Channel::Api",
"id": 0,
"inbox_id": 0,
"status": "open",
"agent_last_seen_at": 0,
"contact_last_seen_at": 0,
"timestamp": 0
},
"account": {
"id": 1,
"name": "API testing"
},
"event": "message_created"
}
Crear interfaces usando APIs cliente
Las APIs cliente disponibles para el canal API te ayudarán a construir interfaces orientadas al cliente para Chatwoot.
Estas APIs son útiles para casos como los listados a continuación.
-
Usar una interfaz de chat personalizada en lugar del widget de chat de Chatwoot.
-
Construir interfaces conversacionales en tus aplicaciones móviles.
-
Agregar Chatwoot a otras plataformas para las que Chatwoot no tenga un SDK oficial.
Creando objetos de cliente
Puedes crear y recuperar objetos de datos de clientes usando el inbox_identifier y el customer_identifier.
Identificador de Buzón
Puedes obtener el inbox_identifier desde tu canal API -> Configuración -> Configuración.
Identificador de Cliente
El customer_identifier o source_id se puede obtener al crear el cliente utilizando la API de crear. Deberás almacenar este identificador en tu lado cliente para realizar más solicitudes en nombre del cliente. Esto se puede hacer en cookies, almacenamiento local, etc.
APIs Disponibles
Las APIs cliente disponibles están documentadas aquí. Algunas de las cosas que puedes hacer con las APIs son:
-
Crear, Ver y Actualizar Contactos
-
Crear y Listar Conversaciones
-
Crear, Listar y Actualizar Mensajes
Autenticación HMAC
Las APIs cliente también soportan Autenticación HMAC. El token HMAC del canal puede obtenerse ejecutando lo siguiente en tu consola de rails.
# reemplaza api_inbox_id con tu id de buzón
Inbox.find(api_inbox_id).channel.hmac_token
Conectar a los WebSockets de Chatwoot
Para obtener actualizaciones en tiempo real desde el panel de agente, conéctate a los WebSockets de Chatwoot usando la siguiente URL.
<your installation url>/cable
Autenticando tu conexión WebSocket
Después de suscribirte usando el pubsub_token del cliente, recibirás eventos dirigidos hacia tu objeto cliente. El pubsub_token se proporciona durante la llamada API de creación del cliente.
Ejemplo
const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));
Encuentra la lista completa de eventos soportados por WebSockets aquí.
Verificación de Webhook
Una vez que crees un canal API, generamos automáticamente un secreto que puedes usar para verificar la carga útil que recibe tu aplicación. Puedes leer más sobre la verificación de webhooks aquí.
Implementación
He aquí un ejemplo de interfaz de chat construida sobre las APIs cliente.