Cómo Crear un Canal de Inbox de API en WhatChat

Configuración del Canal de API #

Paso 1: Accede a Configuración → Buzones → “Añadir Buzón”.

Paso 2: Haz clic en el icono «API».

Paso 3: Proporciona un nombre para el canal y una URL de callback. Ejemplo:

Paso 4: Añade agentes a tu buzón de API.

La configuración del buzón está completa.

Envío de Mensajes al Canal de API #

Para enviar mensajes al canal de API, es fundamental comprender los siguientes modelos y nomenclatura utilizados en WhatChat:

1. Canal: Define el tipo de fuente de las conversaciones (ej. Facebook, Twitter, API, etc.).
2. Buzón: Puedes crear múltiples fuentes de conversación del mismo tipo de canal (por ejemplo, más de una página de Facebook conectada a una cuenta de WhatChat).
3. Conversación: Una colección de mensajes.
4. Contacto: Una persona real asociada a cada conversación.
5. Buzones de Contacto: Sesiones para cada contacto en un buzón. Un contacto puede tener múltiples sesiones y conversaciones en el mismo buzón.

¿Cómo enviar un mensaje en un Canal de API? #

Para enviar un mensaje en un canal de 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 accediendo a tu perfil → Configuración del Token de Acceso.

1. Crear un contacto

Referencia: Documentación de API

Envía el ID del buzón del canal de API junto con otros parámetros especificados. Esto creará automáticamente una sesión para ti. Una respuesta de ejemplo se vería así:

{
  "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"
}

En el paquete de respuesta, podrás observar los contact_inboxes, donde cada contact_inbox tendrá un source_id, que puede considerarse como el identificador de sesión. Usarás este source_id para crear una nueva conversación, como se define a continuación.

2. Crear una conversación

Referencia: Documentación de API

Utiliza el source_id recibido en la llamada de API anterior. Recibirás un ID de conversación que puedes usar para crear un mensaje.

{
  "id": 0
}

3. Crear un nuevo mensaje

Referencia: Documentación de API

Existen dos tipos de mensajes:

1. Entrante: Mensajes enviados por el usuario final.
2. Saliente: Mensajes enviados por el agente.

Si llamas a la API con el contenido correcto, recibirás un paquete similar a este:

{
    "id": 0,
    "content": "Este es un mensaje entrante desde el Canal de API",
    "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 ha salido bien, podrás ver la conversación en el panel de control.

Serás notificado cuando se cree un nuevo mensaje en la URL especificada al crear el canal de API. Puedes leer sobre el contenido del mensaje aquí.

Recibir Mensajes Usando la URL de Callback #

Cuando se crea un nuevo mensaje en el canal de API, recibirás una solicitud POST en la URL de Callback especificada al crear el canal. El paquete se verá así:

Encuentra la lista completa de eventos soportados por el webhook aquí.

Tipo de evento: message_created

{
  "id": 0,
  "content": "Este es un mensaje entrante desde el Canal de API",
  "created_at": "2020-08-30T15:43:04.000Z",
  "message_type": "incoming",
  "content_type": null,
  "content_attributes": {},
  "source_id": null,
  "sender": {
    "id": 0,
    "name": "nombre-de-contacto",
    "avatar": "",
    "type": "contact"
  },
  "inbox": {
    "id": 0,
    "name": "Canal API"
  },
  "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": "Prueba API"
  },
  "event": "message_created"
}

Crear Interfaces Usando APIs de Cliente #

Las APIs de cliente disponibles para el canal de API te ayudarán a construir interfaces orientadas al cliente para WhatChat.

Estas APIs son útiles para casos como:

1. Utilizar una interfaz de chat personalizada en lugar del widget de chat de WhatChat.
2. Construir interfaces conversacionales en tus aplicaciones móviles.
3. Integrar WhatChat en otras plataformas para las cuales WhatChat no tiene un SDK oficial.

Creación de Objetos de Cliente #

Puedes crear y recuperar objetos de datos de clientes utilizando el inbox_identifier y el customer_identifier.

Identificador de Buzón

Puedes obtener el inbox_identifier desde tu canal de API → Configuración → Configuración.

Identificador de Cliente

El customer_identifier o source_id se puede obtener al crear el cliente usando la API de creación. Necesitarás almacenar este identificador en el lado del cliente para hacer solicitudes posteriores en nombre del cliente, lo cual se puede hacer utilizando cookies, almacenamiento local, etc.

APIs Disponibles

Las APIs de cliente disponibles están documentadas aquí. Algunas de las acciones que puedes realizar son:

• Crear, visualizar y actualizar contactos.
• Crear y listar conversaciones.
• Crear, listar y actualizar mensajes.

Autenticación HMAC #

Las APIs de cliente también soportan autenticación HMAC. El token HMAC para el canal se puede obtener 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

Conexión a los WebSockets de WhatChat #

Para recibir actualizaciones en tiempo real desde el panel del agente, conéctate a los WebSockets de WhatChat utilizando la siguiente URL:

<tu url de instalación>/cable

Autenticación de tu conexión WebSocket #

Después de suscribirte usando el pubsub_token del cliente, recibirás eventos dirigidos a tu objeto cliente. El pubsub_token se proporciona durante la llamada de API para crear el 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í.