API-ISV Connecto To BotChattigo

Nuestra API permite a los clientes ISV (Proveedor de Software Independiente) conectarse a BOT-CHATTIGO y configurar respuestas personalizadas dentro del bot. Esta solución permite a los ISV definir las respuestas que desean proporcionar a sus clientes y proporciona la estructura de datos necesaria para enviar mensajes directamente a WhatsApp, facilitando la comunicación sin problemas.

Novedades

Conexión ISV-BOT

La API facilita la conexión entre los ISV y BOT-CHATTIGO, permitiendo una interacción fluida.

Configuración de Respuestas

Los ISV pueden configurar las respuestas que desean que el bot entregue a sus clientes.

Manejo de Mensajes Inbound

Cuando los ISV reciben un mensaje entrante en WhatsApp, pueden enviarlo a nuestro endpoint después de un inicio de sesión exitoso.

Webhooks Personalizados

Los ISV tienen la capacidad de establecer sus propios webhooks en nuestra base de datos (Chattigo).

Procesamiento de Mensajes

Chattigo procesa los mensajes exactamente según la estructura que proviene de WhatsApp.

Entrega de Respuestas

La API proporciona la estructura de datos necesaria para enviar varios tipos de mensajes directamente a los clientes, incluyendo Mensajes de Plantilla, Mensajes de Texto, Mensajes de Contenido Multimedia, Mensajes de Reacción, Mensajes de Ubicación, Mensajes de Contacto y Mensajes Interactivos.

Flexibilidad

Los ISV pueden tomar decisiones basadas en la respuesta y decidir cómo manejarla.

Esta API brinda a los ISV la capacidad de personalizar y controlar las respuestas en sus interacciones con los clientes, al mismo tiempo que les proporciona la estructura esencial para la comunicación efectiva en WhatsApp en diversos formatos de mensajes.

Autenticación

Servicio para obtener el token de autenticación que debe ser usado en cada iteración. La vigencia es de 8 horas y es válido sólo para el usuario logueado. A continuación se presenta la estructura que requiere la api para obtener el JWT de autenticación. Para el servicio de mensajería utilizando la estructura de API Cloud de WhatsApp es necesario proveer una versión de la misma, en inicio se utilizarán las versiones 14.0 y 15.0, en la medida en que se vayan incorporando nuevas versiones por parte de meta, se iran incluyendo.

Para hacer un request a la ruta POST /login es necesario enviar el siguiente Json en el Body de la petición:

   {
       "username": "<user>",
       "password":"<password>"
   }

En caso satisfactorio se obtendrá una Response que contendrá el access_token necesario para realizar luego las peticiones necesarias con el Api.

   {
  "user": "<user>",
  "access": true,
  "access_token": "<token valid>"
}

Envío de Mensajeria a chattigo

Cuerpo del mensaje a recepcionar:

Para el caso de los mensajes inbound que quiera enviar a Chattigo para ser procesados por el BOT-CHATTIGO, aqui se encuentra en la documentación de Meta

Para enviarlos, realice una llamada POST /webhooks/inbound

La ruta PATCH /webhooks/outbound será el servicio para agregar o cambiar el endpoint que permitirá la recepción de las respuestas que provienen desde chattigo, para ello se debe enviar un Header de la siguiente manera:

   ["Authorization" : "<JWT>"]

En el Body será necesario introducir un payload con mínimo los siguientes datos:

{
  "waId": "<identificador del canal>",
  "externalWebhookIsvBot": "<URL segura HTTPS>"
}

Definición de Objeto

Response

StatusCode 200

{
  "waId": "<identificador del canal>",
  "externalWebhookIsvBot": "<URL segura HTTPS>"
}

A continuación exponemos un ejemplo de body de algunos de las respuestas que va a recibir de chattigo :

Plantillas

Para el caso del envío de plantillas recibira un payload como el siguiente:

{
  "messaging_product": "whatsapp",
  "to": "{{Recipient-WA-ID}}",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": {
      "code": "en_US"
    }
  }
}

Texto

Para el caso del envío de mensajes de texto recibira un payload como el siguiente:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{Recipient-Phone-Number}}",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "text-message-content"
  }
}

Multimedia

En API Cloud la mensajería de multimedia contiene todos los tipos de mensajes incluidos los stickers y los documentos.
Para el caso de mensajes de multimedia recibira un payload como el siguiente:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{Recipient-Phone-Number}}",
  "type": "image",
  "image": {
    "link": "http(s)://image-url"
  }
}

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{Recipient-Phone-Number}}",
  "type": "document",
  "document": {
    "link": "http(s)://document-url"
  }
}

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{Recipient-Phone-Number}}",
  "type": "sticker",
  "sticker": {
    "link": "http(s)://sticker-url"
  }
}

Se pueden recibir los tipos audio, document, image, sticker o video, para todos los casos solo se vera el cambio de referencia en el type de mensaje a enviar y la key en el payload.

Para todos los casos en la mensajería la respuesta satisfactoria será 200

Avisos de cierre de mensajeria por parte de bot-chattigo

Cuando las conversaciones por parte de chattigo finalizen, se enviara un aviso como este en conjunto a la respuesta de cierre.

{
  "chatBeenClosed":{
    "closed":true,
    "message":"El chat finalizo"
  }
}

Errores

Existen varios tipos de errores, algunos generales y otros específicos por cada endpoint a continuación se desglosan:

Errores Generales

Los endpoints que necesitan autorización por token presentan los siguientes errores

401 (Token incorrecto)

{
  "message": "JWT was invalid"
}

401 (Token con permisos insuficientes)

{
  "message": "unauthorized Access"
}

401 (Token vacio)

{
  "message": "token up for parsing was not passed through the header. Please read the API documentation at https://development.chattigo.com"
}

Errores específicos

POST /login

400 (Contraseña incorrecta)

{
"message": "invalid Password"
}

400 (Usuario incorrecto)

{
  "message": "unsupported get request. username ‘bad_login’ does not exist, or an unexpected error has occurred with your service provider"
}

PATCH /webhooks/inbound

400 (waId incorrecto en el payload de entrada)

{
  "message": "unsupported get request. Object with ID 'XXXXXXX' does not exist"
}