API Bot

Integra tus bots para gestionar la atención desde Chattigo.

Descripción General

Multi-Campaña: Cuando se requiera hacer un pase a Agente desde el BOT, se debe enviar al API-BOT en el campo “idCampaign” el identificador de la campaña y en el campo “type” el valor “transfer”. Campaña-Grupo: Cuando se requiera hacer un pase a Agente desde el BOT, se debe enviar al API-BOT en el campo “idCampaign” el identificador de la campaña, en el campo “type” el valor “group” y en el campo “content” el código del grupo. Mono-Campaña: Cuando se requiera hacer un pase a Agente, no se enviará el campo “idCampaign” y el campo “type” tendrá el valor “transfer”. Transfer al BOT: Una vez finalizada la atención por parte del Agente, se cierra el chat y se envía un mensaje al BOT con el valor “transfer” en el campo “type”, para que continúe el flujo del mismo y libere la sesión. Cierre Interacción: Finalizado el flujo del BOT se envía al API-BOT un mensaje con el valor “close” en el campo “type”, de esta forma el flujo se cierra completamente. Cierre por Inactividad: Finalizado el flujo del BOT por inactividad se envía al API-BOT un mensaje con el valor “timeout” en el campo “type”, de esta forma el flujo se cierra completamente.

Autenticación

Servicio para obtener el token de autenticación para ser usado en cada iteración. La vigencia es de 8 horas, 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.

Path:

POST /login

  • Request

    • Body:
   {
       "username": "<user>",
       "password":"<password>"
   }
  • Response

    • Body:
   {
       "access_token": "<JWT>"
   }
Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Webhook de mensajes

Servicio que permite la entrega de mensajes al bot de atención, considerar la siguiente estructura:

Path:

POST /{URL https entregada por el cliente}

  • Request

    • Body:
{
   "id": 364096945,
   "idChat": 29289561,
   "did": "573175180237",
   "msisdn": "573127439126",
   "idUser": 0,
   "type": "Text",
   "channel": "WHATSAPP",
   "channelProvider": "WAVY",
   "content": "21812660",
   "name": "Camila Ochoa",
   "idCampaign": 597,
   "isAttachment": false,
   "attachment": null,
   "message": null
}

Response

Status Code 200

Errors

StatusCode: 400 Bad Request

StatusCode: 500 Internal Server Error

Type Message

Tipo Descripción
transfer Cuando el agente cierra la conversación y notificar al bot para que contiene con el flujo
text Cuando es un mensaje de tipo texto
media Cuando es un mensaje de tipo multimedia

Envío de mensaje

Servicio que permite el envío de respuestas del BOT al cliente, considerar la siguiente estructura:

Path:

POST /outbound

  • Request

    • Header:
  ["Authorization" : "Bearer <JWT>"]
  • Body (message type text):
{
   "id": 364096892,
   "idChat": 0,
   "did": "5491165972035",
   "msisdn": "5493794236459",
   "idUser": 0,
   "type": "text",
   "channel": "WHATSAPP",
   "channelProvider": "provider",
   "content": "example",
   "name": "Bot",
   "idCampaign": 353,
   "message": null,
   "idNode": 40934,
   "nameNode": "7_agente",
   "botName": "09_opcion8",
   "isAttachment": false,
   "attachment": null
}
  • Body (message type media):
{
   "id": 364096892,
   "idChat": 0,
   "did": "5491165972035",
   "msisdn": "5493794236459",
   "idUser": 0,
   "type": "media",
   "channel": "WHATSAPP",
   "channelProvider": "provider",
   "content": "example",
   "name": "Bot",
   "idCampaign": 353,
   "message": null,
   "idNode": 40934,
   "nameNode": "7_agente",
   "botName": "09_opcion8",
   "isAttachment": true,
   "attachment": {
       "mediaUrl":"https://ejemplo.url.com/documento_ejemplo.pdf",
       "mimeType":"application/pdf",
       "fileName":"NombreDelFichero.pdf"
    }
}

Response

 Status Code 200

Errors

 StatusCode 400 - Bad Request

 StatusCode 500 - Internal Server Error

Type Message

Tipo Descripción
transfer Cuando en el flujo del BOT se hace un pase a agente.
transfer-external Cuando en el flujo del BOT se hace un pase a un servicio externo.
text Cuando es un mensaje de tipo texto.
media Cuando es un mensaje de tipo multimedia.
close/timeout Cuando termina el flujo del BOT.
internal Cuando es un mensaje que no se envía al cliente final pero queda en el chat.

Mensajes Interactivos

Servicio para enviar mensajes interactivos aceptados por Facebook o WhatsApp adaptados al siguiente formato:

Path:

POST /outbound

  • Request

    • Header:
  ["Authorization" : "Bearer <JWT>"]
  • Body - Mensaje Interactivo de WhatsApp:
{
  "did": "",
  "msisdn": "",
  "type": "text",
  "channel": "WHATSAPP",
  "channelProvider": "BSPCHATTIGO",
  "content": "",
  "name": "",
  "idCampaign": "",
  "isAttachment": false,
  "message": {},
  "botProvider": "CHATTIGO",
  "interactiveMsg": {
    "body": "Selecciona una opción",
    "choices": [
      {
        "id": "620c017d3a",
        "text": "Opción 1"
      },
      {
        "id": "628559f25b",
        "text": "Opción 2"
      }
    ],
    "interactiveType": "",
    "titleList": "Opciones"
  }
}
  • Body - Mensaje Interactivo de Messenger:
{
    "msisdn": "",
    "did": "",
    "type": "template",
    "channel": "MESSENGER",
    "channelProvider": "FACEBOOK",
    "isAttachment": false,
    "idCampaign": "",
    "message": {
        "attachment": {
            "type": "template",
            "payload": {
                "template_type": "button",
                "text": "Selecciona una opción",
                "buttons": [
                    {
                        "type": "postback",
                        "payload": "Option1",
                        "title": "Esta es la opción 1"
                    },
                    {
                        "type": "postback",
                        "payload": "Option2",
                        "title": "Esta es la opción 2"
                    }
                ]
            }
        }
    }
}

Response

 Status Code 200
  • Body - Mensaje Interactivo de WhatsApp:
{
   "id":"2121180956",
   "idChat":152151222,
   "chatType":"INBOUND",
   "did":"56945070713",
   "msisdn":"56932562172",
   "type":"Text",
   "channel":"WHATSAPP",
   "channelProvider":"APICLOUDBSP",
   "content":"Option 1",
   "name":"Receptor",
   "idCampaign":"2219",
   "isAttachment":false,
   "interactiveChoiceId":"Option1-620c017d3aa7d67818cff327"
}

La opción seleccionada por el receptor vendrá dentro del campo interactiveChoiceId.

  • Body - Mensaje Interactivo de Messenger:
{
   "id":"2094966795",
   "idChat":88683807,
   "chatType":"INBOUND",
   "did":"107533292125305",
   "msisdn":"6084054358291240",
   "type":"text",
   "channel":"MESSENGER",
   "channelProvider":"FACEBOOK",
   "content":"Option1",
   "name":"Receptor",
   "idCampaign":"1988",
   "isAttachment":false,
   "attachment":{
      "mimeType":""
   }
}

La opción seleccionada por el receptor vendrá dentro del campo content con el valor previamente seteado en el campo postback del button.

Errors

 StatusCode 400 - Bad Request
 
 StatusCode 401 - Unauthorized

 StatusCode 500 - Internal Server Error

Mensaje Interactivo de WhatsApp

Tipo Descripción Tipo de dato
did Tu numero de WhatsApp en Chattigo string
msisdn Número de WhatsApp al que deseas enviar un mensaje string
channelProvider Proveedor del número de WhatsApp (BSPCHATTIGO o APICLOUDBSP) string
idCampaign Identificador de la campaña string
botProvider Proveedor del servicio de Bot string
interactiveMsg Objeto con el contenido del mensaje interactivo object
body Texto de titulo de las opciones string
choices Arreglo de lista de opciones array
choice id Identificador de la opción string
choice text Texto de la opción string
interactiveType Tipo de mensaje interactivo (list o button) string
titleList Titulo en caso que el mensaje sea de tipo lista string

Mensaje Interactivo de Messenger

Tipo Descripción Tipo de dato
msisdn Identificador del usuario de Messenger al que deseas enviar un mensaje string
did Tu idenficador de usuario de Messenger string
idCampaign Identificador de la campaña string
message Objeto con el contenido del mensaje interactivo object
payload text Texto titular de la botonera string
buttons Arreglo de botonera de opciones (Maximo 3 opciones) array
button payload Identificador de la opcion de la botonera string
button text Texto de la opción string

Servicio para enviar mensajes de productos mediante el catálogo conectado a tu número de WhatsApp (requiere un catálogo activado en chattigo).

Path:

POST /outbound

  • Request

    • Header:
  ["Authorization" : "Bearer <JWT>"]
  • Body:
{
  "idChat": "<identificador de chat>",
  "did": "<identificador de canal>",
  "msisdn": "<número del receptor>",
  "type": "catalog",
  "channel": "WHATSAPP",
  "channelProvider": "provider",
  "name": "<nombre>",
  "idCampaign": "<identificador de campaña>",
  "catalog": {
    "catalogId": "<identificador del catalogo>",
    "products": [
      {
        "id": "<identificador del producto, retailer>",
        "productImage": "<link de imagen del producto>"
      },
      {
        "id": "<identificador del producto, retailer>",
        "productImage": "<link de imagen del producto>"
      }
    ],
    "totalItems": 2,
    "title": "Catalogo de productos",
    "body": "Mira estos productos en oferta"
  }
}

Puedes enviar hasta 30 productos por mensaje.

Response

 Status Code 200

Errors

 StatusCode 400 - Bad Request
 
 StatusCode 401 - Unauthorized

 StatusCode 500 - Internal Server Error

Mensaje de tipo catálogo (envío de productos)

Tipo Descripción Tipo de dato
idChat Identificador del chat number
did Tu numero de WhatsApp en Chattigo string
msisdn Número de WhatsApp al que deseas enviar un mensaje string
type Tipo de mensaje, en estos caso es ‘catalog’ string
channel Tipo de canal, en estos caso es ‘WHATSAPP’ string
name Nombre del usuario que envía el mensaje string
idCampaign Identificador de la campaña string
catalog Objeto catalogo object
catalogId Identificador del catalogo string
products Listado de productos a enviar array
id Identificador del producto, debe ser el retailer id introducido en Meta string
productImage URL a la imagen del producto, opcional string
totalItems Cantidad total de productos enviados number
title Titulo del catalogo enviado string
body Mensaje adjunto al catalogo enviado string

Mensajes recibidos de tipo order (carrito de compras)

Mediante el webhook también podremos recibir mensajes de carritos de compras de productos si tienes catálogo conectado a tu número de WhatsApp (requiere un catálogo activado en chattigo).

  • Body:
{
  "id": "<identificador del mensaje>",
  "idChat": "<identificador de chat>",
  "chatType": "<tipo de chat>",
  "did": "<identificador de canal>",
  "msisdn": "<número del emisor>",
  "type": "order",
  "channel": "WHATSAPP",
  "channelProvider": "APICLOUDBSP",
  "content": "",
  "name": "<nombre del emisor>",
  "idCampaign": "<identificador de la campaña>",
  "order": {
    "catalog_id": "<identificador del catalogo>",
    "totalItems": 4,
    "totalPrice": 127.96,
    "product_items": [
      {
        "product_retailer_id": "<identificador del producto>",
        "quantity": 3,
        "item_price": 15.99,
        "currency": "USD"
      },
      {
        "product_retailer_id": "<identificador del producto>",
        "quantity": 2,
        "item_price": 10.99,
        "currency": "USD"
      }
    ],
    "text": "Quiero estos productos"
  }
}

Mensajes recibidos de tipo order (carrito de compras)

Tipo Descripción Tipo de dato
id Identificador del mensaje string
idChat Identificador del chat number
chatType Tipo de chat, ejemplo: INBOUND, OUTBOUND string
did Tu numero de WhatsApp en Chattigo string
msisdn Número de WhatsApp al que deseas enviar un mensaje string
type Tipo de mensaje, en estos caso es ‘order’ string
channel Tipo de canal, en estos caso es ‘WHATSAPP’ string
channelProvider Proveedor del número de WhatsApp (BSPCHATTIGO o APICLOUDBSP) string
name Nombre del usuario que envía el mensaje string
idCampaign Identificador de la campaña string
order Objeto order, será el carrito de compras que nos envíen object
catalog_id Identificador del catalogo string
totaItems Cantidad total de items (productos) dentro del carrito number
totalPrice Precio total de la suma de todos los productos del carrito number
text Mensaje adjunto al carrito string
product_items Listado de productos del carrito recibido array
product_retailer_id Identificador del producto, será el retailer id del producto en Meta string
quantity Cantidad total de producto especifico number
item_price Precio del producto especifico number
currency Moneda en la cual está cotizado el precio del producto number

Mensajes recibidos de producto citado

Si tienes un catálogo conectado puede darse el caso de que un cliente cite un producto para hacer consultas sobre el mismo. Recuerda que para estos mensajes necesitas un número de WhatsApp y un catálogo activado en chattigo.

  • Body:
{
  "id": "<identificador del mensaje>",
  "idChat": "<identificador de chat>",
  "chatType": "<tipo de chat>",
  "did": "<identificador de canal>",
  "msisdn": "<número del emisor>",
  "type": "Text",
  "channel": "WHATSAPP",
  "channelProvider": "APICLOUDBSP",
  "content": "<mensaje del cliente>",
  "name": "<nombre del emisor>",
  "idCampaign": "<identificador de la campaña>",
  "referredProduct": {
    "id": "<identificador del producto>",
    "name": "<nombre del producto>",
    "catalogId": "<identificador del catalogo>",
    "imageUrl": "<link de imagen del producto>",
    "price": "$79,99",
    "currency": "USD",
    "url": "<link a la url del producto>"
  }
}

Mensajes recibidos de tipo order (carrito de compras)

Tipo Descripción Tipo de dato
id Identificador del mensaje string
idChat Identificador del chat number
chatType Tipo de chat, ejemplo: INBOUND, OUTBOUND string
did Tu numero de WhatsApp en Chattigo string
msisdn Número de WhatsApp al que deseas enviar un mensaje string
type Tipo de mensaje, en estos caso es ‘Text’ string
channel Tipo de canal, en estos caso es ‘WHATSAPP’ string
channelProvider Proveedor del número de WhatsApp (BSPCHATTIGO o APICLOUDBSP) string
name Nombre del usuario que envía el mensaje string
idCampaign Identificador de la campaña string
referredProduct Objeto referredProduct, es el producto el cual el usuario cita object
id Identificador del producto, será el retailer id del producto en Meta string
name Nombre del producto string
catalogId Identificador del catalogo string
imageUrl URL a la imagen del producto string
price Precio del producto string
currency Moneda en la cual está cotizado el precio del producto string
url Link de Meta asociado al producto string

Mensajes Interactivos de tipo FLOW

Configuración de los mensajes interactivos para enviar y recibir respuesta de tipo FLOW

Path

POST /outbound

  • Request

    • Header:
["Authorization" : "Bearer <JWT>"]

Body - Mensaje tipo FLOW de WhatsApp:

{
  "idChat": 88693329,
  "did": "5215639549199",
  "msisdn": "5491156998799",
  "type": "text",
  "channel": "WHATSAPP",
  "channelId": 10048,
  "channelProvider": "APICLOUDBSP",
  "idCampaign": "1998",
  "isAttachment": false,
  "botProvider": "CHATTIGO",
  "interactiveMsg": {
    "action": {
      "name": "flow_name",
      "parameters": {
        "flowAction": "navigate",
        "flowActionPayload": {
          "screen": "QUESTION_ONE"
        },
        "flowCta": "Inscribirse",
        "flowId": "419018317132842"
      }
    },
    "body": "Contenido del mensaje",
    "interactiveType": "flow"
  }
}

Response

Status Code 200
{
"code": "200",
"message": "Message sent"
}

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

StatusCode 500 - Internal Server Error

El contenido de los campos del flow completados por el usuario vendrán dentro del objeto FLOW en el array components en el objeto value

{
  "id": "58848",
  "idChat": 88693329,
  "chatType": "INBOUND",
  "did": "5215639549199",
  "msisdn": "5491156998799",
  "type": "flow",
  "channel": "WHATSAPP",
  "channelId": 10048,
  "channelProvider": "APICLOUDBSP",
  "content": "Sent",
  "name": "User test",
  "idCampaign": "1998",
  "isAttachment": false,
  "messageDate": 1706201843570,
  "flow": {
    "screens": [
      {
        "screen_id": "QUESTION_ONE",
        "screen_title": "Screen de prueba",
        "screen_terminal": true,
        "components": [
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_0",
            "label": "Nombre",
            "value": [
              "Nombre del usuari"
            ],
            "Index": 0
          },
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_1",
            "label": "Apellido",
            "value": [
              "Apellido del usuario"
            ],
            "Index": 1
          },
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_2",
            "label": "Dirección",
            "value": [
              "Siempre Viva 1234"
            ],
            "Index": 2
          },
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_3",
            "label": "Email",
            "value": [
              "test@chattigo.com"
            ],
            "Index": 3
          },
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_4",
            "label": "Teléfono",
            "value": [
              "1111111"
            ],
            "Index": 4
          },
          {
            "type": "TextInput",
            "required": true,
            "name": "screen_0_TextInput_5",
            "label": "DNI",
            "value": [
              "1111111"
            ],
            "Index": 5
          }
        ]
      }
    ]
  }
}

Mensaje tipo FLOW de WhatsApp

Tipo Descripción Tipo de dato
did Tu numero de WhatsApp en Chattigo string
msisdn Número de WhatsApp al que deseas enviar un mensaje string
channelProvider Proveedor del número de WhatsApp (BSPCHATTIGO o APICLOUDBSP) string
idCampaign Identificador de la campaña string
botProvider Proveedor del servicio de Bot string
interactiveMsg Objeto con el contenido del mensaje interactivo object
→ action Objeto con el contenido del flow interactivo object
→ → name nombre asignado al flow array
→ → parameters Objeto con los paramteros del flow object
→ → → flowAction Action del flow (navigate) string
→ → → flowActionPayload Objeto con la Screen Inicial object
→ → → → screen Nombre de la screen inicial string
→ → → flowCta Etiqueta en el botón del flow string
→ → → flowId Id del flow a enviar string
→ interactiveType Tipo de mensaje interactivo (must be “flow”) string
→ body Mensaje a enviar con el flow string

Obtener mensajes HSM

Servicio para la obtención de mensajes HSM que no han sido procesado por el bot, considerar la siguiente estructura:

Path:

GET /messages/{channel}/{did}/{msisdn}

Params

Parámetro Descripción
channel WHATSAPP
did identificador del canal
msisdn identificador del cliente
  • Request

    • Header:
  ["Authorization" : "Bearer <JWT>"]
  • Response

    • Body:
[
   {
           "id_mensaje": 0000,
           "contenido": "<Contenido del mensaje>",
           "fecha_hora": "2000-01-01T00:00:00.000+0000"
        }
]
Status Code 200

Errors StatusCode 400 - Bad Request

 StatusCode 500  - Internal Server Error

Notificación de resolución

Servicio para notificar la resolución que tiene un mensaje de alerta, considerar la siguiente estructura:

Path:

POST /resolution

  • Request
    • Header:
   ["Authorization" : "Bearer <JWT>"]
  • Body:
{
   "id": "<identificador>",
   "did": "<identificador del canal>",
   "answer": "true|false"
}

Response

StatusCode 200

Errors

StatusCode 400 - Bad Request

StatusCode 500 - Internal Server Error

Definición de Objeto

Fields Type Mandatory Descripción
id int yes Identificador del mensaje
did String yes identificador del canal
answer Boolean yes Respuesta del cliente True / False

Agentes disponibles

Servicio que entrega la lista de agentes disponibles para atención, considerando la siguiente estructura:

Path:

GET /agent/active/{did}

Params

Parámetro Descripción
did identificador del canal
  • Request
    • Header:
   ["Authorization" : "Bearer <JWT>"]

Response

StatusCode 200

  • Body:
[       
   {
       "id": 6000,
       "name": "asesor virtual 1",
       "address": "",
       "maxChats": 3,
       "activeChat": 0,
       "active": true,
       "idClient": 331,
       "photo": "",
       "status": "",
       "chatAssigned": 0,
       "groups": null
   },
   {
       "id": 6001,
       "name": "asesor virtual 2",
       "address": "",
       "maxChats": 3,
       "activeChat": 0,
       "active": true,
       "idClient": 331,
       "photo": "",
       "status": "",
       "chatAssigned": 0,
       "groups": null
   }
 
]

Errors

StatusCode 400 - Bad Request

StatusCode 500 - Internal Server Error

Fuera de horario

Servicio que permite al BOT identificar si la campaña está disponible para atender al cliente, considerando la siguiente estructura:

Path:

GET /timeout/{idMessage}/{idCampaing}

Params

Parámetro Descripción
idMessage Corresponde al identificador del mensaje (campo ID)
idCampaing identificador de la campaña a transferir
  • Request
    • Header:
   ["Authorization" : "Bearer <JWT>"]

Response

StatusCode 200

  • Body:
{
   "outOfTime": "true|false",
   "messageOutOfTime": "Esta campaña no está disponible por el momento",
   "queue": "20"
}

Errors

StatusCode 400 - Bad Request

StatusCode 500 - Internal Server Error

Validar agentes existentes en campañas

Servicio que valida si hay agentes presentes en una campaña:

Path:

POST /webhook/chattigo/crm/create

  • Body:
   [
      {
      "identificadorAgente": "{{AGENT_NAME}}",
      "idCampana": "{{CAMPAIGN_ID}}",
      "agentValues":[
         {
               "key": "agente1condor",
               "value": 18861  
         },
         {
               "value": 18862,
               "key": "agente2condor"
         },
         {
               "value": 18863,
               "key": "agente3condor"
         }
      ]
      }
   ]

Definición de Objeto

Fields Type Mandatory Descripción
identificadorAgente String yes Nombre de agente a validar
idCampana Int yes Identificador del canal
agentValues Array yes Array de nombres de agentes e IDs
value Int yes Id de agente en chattigo
key String yes Nombre de agente

Nota de uso: Los parametros value y key hacen referencia a NOMBRE DE AGENTE e ID DE AGENTE respectivamente, el json presentado posee informacion de ejemplo.

  • Response

    • Body:
   [
      {
         "code": 200,
      }
   ]

Errors

StatusCode 400 - Bad Request

StatusCode 500 - Internal Server Error

Transferencia a agente especifico offline

Servicio que transfiere un chat a un agente en especifico:

Path:

POST /api_bot_outbound_condor/generic/event

  • Body:
   [
      {
         "idChat": "{{idChat}}",
         "chatType": "INBOUND",
         "did": "{{did}}",
         "msisdn": "{{msidn}}",
         "type": "transfer-agent-offline",
         "idUser": "{{idUser}}",
         "channel": "WHATSAPP",
         "channelProvider": "APICLOUDBSP",
         "idCampaign": "{{idCampaign}}",
         "isAttachment": false,
         "botProvider": "CHATTIGO"
      }
   ]

Definición de Objeto

Fields Type Mandatory Descripción
idChat Int yes Identificador del chat
chatType String yes identificador del canal
did Int yes Did del canal
msisdn Int yes Numero de telefono del cliente
type String yes Tipo de transferenci
idUser Int yes Identificador del usuario
channel String yes Tipo de canal
channelProvider String yes Proveedor del canal
idCampaign Int yes Identificador de campana chat
isAttachment Bool yes Validacion de adjunto
botProvider String yes Proveedor de bot

Nota de uso: Los parametros que tienen palabras escritas en duro como “INBOUND” son fijas y no deben ser cambiadas.

  • Response

    • Body:
   [
      {
         "code": 200,
      }
   ]

Errors

StatusCode 400 - Bad Request

StatusCode 500 - Internal Server Error