API HSM

Realiza envíos masivos a través de la API de WhatsApp Oficial.

Autenticación

Servicio para obtener el token de autenticación para 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.

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

Envío de template a varios destinatarios con parámetros estáticos y dinámicos

Para el envío de un mismo HSM a varios destinatarios se debe poner un payload como se muestra a continuación. Es importante usar SOLO ESTE METODO al momento de enviar el mismo template a varios destinos para mejorar el rendimiento de la plataforma.

En el payload se puede observar como se adicionan los distintos tipos de parámetros, tanto estáticos como dinámicos.

Dentro del objeto destinations se envía un <customer_message_id> SOLO en caso de que el cliente cuente con dicha funcionalidad.

La plataforma permite HASTA 1000 destinatarios en cada envío

Path:

POST /inbound

Request
- Header:

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

Body

   {
  "did": "<did>",
  "type": "HSM",
  "channel": "WHATSAPP",
  "hsm": {
    "component": {
      "buttons": [
        {
          "index": 0
        }
      ]
    },
    "destinations": [
      {
        "id": "<customer_message_id>",
        "destination": "<customer_number>",
        "parameters": [
          "<customer_body_dynamic_parameter1>",
          "<customer_body_dynamic_parameter2>",
          "<customer_body_dynamic_parameter3>"
        ],
        "buttonsParameters": [
          "<customer_button_dynamic_parameter1>"
        ],
        "headerParameters": [
          "<customer_dynamic_parameter1>"
        ]
      },
      {
        "id": "<customer1_message_id>",
        "destination": "<customer1_number>",
        "parameters": [
          "<customer1_body_dynamic_parameter1>",
          "<customer1_body_dynamic_parameter2>",
          "<customer1_body_dynamic_parameter3>"
        ],
        "buttonsParameters": [
          "<customer1_button_dynamic_parameter1>"
        ],
        "headerParameters": [
          "<customer1_dynamic_parameter1>"
        ]
      }
    ],
    "parameters": [
      "<body_static_parameter1>",
      "<body_static_parameter2>",
      "<body_static_parameter3>"
    ],
    "buttonsParameters": [
      "<button_static_parameter1>"
    ],
    "headerParameters": [
      "<header_static_parameter1>"
    ],
    
    "namespace": "<namespaces>",
    "template": "<template_name>",
    "botAttention": true,
    "languageCode": "es"
  }

}

A continuación un ejemplo de como se debe enviar un template con parámetros dinámicos a varios destinatarios:

Dentro de destinations debemos introducir los valores necesarios.

Los valores llegarán SOLO a los destinatarios en cuestión

   {
  "did": "56940581384",
  "type": "HSM",
  "channel": "WHATSAPP",
  "hsm": {
    "destinations": [
      {
        "id": "168423779",
        "destination": "359882346677",
        "parameters": [ 
          "Pedro",
          "Juan",
          "Chattigo"
        ],
        "buttonsParameters": [
          "http://www.chattigo.com"
        ],
        "headerParameters": [
          "Chattigo"
        ]
      },
      {
        "id": "2568423779",
        "destination": "3590986924",
        "parameters": [
          "Esteban",
          "Armando",
          "Diana"
        ],
        "buttonsParameters": [
          "http://www.google.com"
        ],
        "headerParameters": [
          "Roberto"
        ]
      }
    ],
    
    "namespace": "8bea77b1_b5db_43a3_ba0c_c927708a17ab",
    "template": "nombre_del_template",
    "botAttention": true,
    "languageCode": "es"
  }

}

A continuación un ejemplo de como se debe enviar un template que contenga un flow que no tenga parámetros Los valores se enviarán en las plantillas a TODOS los destinatarios

{
    "id": "campaign",
    "did": "did",
    "channel": "WHATSAPP",
    "hsm": {
        "totalContactToSend": 1,
        "destinations": [
            {
                "destination": "destination"
            }
        ],
        "template": "prueba_flow_1",
        "botAttention": false,
        "offlineAssignment": false,
        "attends": {
            "attend": 3,
            "assignedAgent": 0,
            "botType": 0,
            "waitTime": -1,
            "typification": 0
        }
    }
}

A continuación un ejemplo de como se debe enviar un template con parámetros estáticos a varios destinatarios: Los valores se enviarán en las plantillas a TODOS los destinatarios

   {
  "id": "<id>",
  "did": "<did>",
  "type": "HSM",
  "channel": "WHATSAPP",
  "hsm": {
    "component": {
      "buttons": [
        {
          "index": 0
        }
      ]
    },
    "destinations": [
      {
        "id": "168423779",
        "destination": "359882346677"
      },
      {
        "id": "2568423779",
        "destination": "3590986924"
      }
    ],
    "parameters": [
      "Compra",
      "Empresa",
      "Chattigo"
    ],
    "buttonsParameters": [
      "http://www.chattigo.com/planes"
    ],
    "headerParameters": [
      "Telefono"
    ],
    
    "namespace": "8bea77b1_b5db_43a3_ba0c_c927708a17ab",
    "template": "nombre_del_template",
    "botAttention": true,
    "languageCode": "es"
  }

}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Envío de Template

Para el envío masivo de mensajes se requiere de un template autorizado por Facebook, el template debe ser habilitado en la plataforma. Dentro de la petición se debe enviar un objeto HSM en el que, dependiendo de la estructura, enviará los distintos tipos de template soportados.

Al momento del envío se requiere integrar la siguiente estructura, en caso de que se desee enviar un template con localización, footer, buttons:

Envío de template de localización con objeto hsm

Path:

POST /inbound

Request
- Header:

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

Body

{
  "id": "<id>",
  "did": "<did>",
  "type": "HSM",
  "channel": "WHATSAPP",
  "hsm": {
    "component": {
      "header": {
        "type": "location",
        "location": {
          "latitude": "<latitude>",
          "longitude": "<longitude>",
          "name": "location name",
          "address": "location name"
        }
      },
      "footer": "<Footer>",
      "buttons": [
        {
          "index": 0,
          "type": "quick_reply",
          "title": "Button Title"
        }
      ]
    },
    "destinations": [
      {
        "destination": "<destination>",
        "parameters": [
          "<body_parameter>"
        ],
        "buttonsParameters": [
          "<button_parameter>"
        ]
      }
    ],
    "namespace": "<namespaces>",
    "template": "<template_name>",
    "botAttention": true,
    "languageCode": "es"
  }
}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Se agregan los siguientes valores en caso de que se desee enviar un template con imagen, footer, buttons:

El tipo de header puede variar dependiendo de tipo de objeto que se quiera enviar.

Envío de template con objeto hsm

Path:

POST /inbound

Request
- Header:

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

Body

   {
      "id": "<id>",
      "did": "<did>",
      "type": "template",
      "channel": "WHATSAPP",
      "hsm": {
        "destinations": [
          {
            "destination": "<destination>"
          }
        ],
        "namespace": "<namespace>",
        "template": "<template_name>",
        "languageCode": "es",
        "botAttention": false,
        "component": {
          "header": {
            "type": "image_url", // text | video | document | payload
            "value": "https://media.chattigo.com/files/media/storage/image_name..jpg",
            "isBinaryFile": true,
            "filename": "<filename>.jpg"
          },
          "footer": "<Footer>",
          "buttons": [
            {
              "index": 0,
              "type": "quick_reply",
              "title": "Button Title"
            }
          ]
        },
        "attends": {
          "attend": 3,
          "assignedAgent": 0,
          "botType": 0,
          "waitTime": -1,
          "typification": 0
        }
  }
}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Envío de template de autenticación con botón de copiar código

Para el envío de este tipo de template, el código que se envía en el template debe tener hasta 15 dígitos.

Path:

POST /inbound

Request
- Header:

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

Body

   {
  "id": "<id>",
  "did": "<did>",
  "type": "HSM",
  "channel": "WHATSAPP",
  "hsm": {
    "component": {
      "buttons": [
        {
          "index": 0
        }
      ]
    },
    "destinations": [
      {
        "destination": "<destination>",
        "parameters": [
          "<body_parameter>"
        ],
        "buttonsParameters": [
          "<button_parameter>"
        ]
      }
    ],
    "namespace": "<namespaces>",
    "template": "<template_name>",
    "botAttention": true,
    "languageCode": "es"
  }

}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Envío de mensaje

Servicio que permite enviar mensajes una vez que se ha generado el envío de HSM y el cliente ha dado respuesta al mensaje. Cuando el cliente responde un HSM se abre una sesión de 24 horas para realizar una conversación, se requiere integrar la siguiente estructura:

Path

POST /inbound/message

Request
- Header:

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

Body

{
   "id": "123123",
   "did": "56949321905",
   "msisdn": "56984643056",
   "type": "media",
   "channel": "WHATSAPP",
   "content": "Imagen chat",
   "name": "Johans Morales",
   "isAttachment": true,
   "attachment": {
       "mimeType": "image/png",
       "mediaUrl": "https://k8s.chattigo.com/files/chattigostorage/Captura-de-Pantalla-2019-06-04-a-la(s)-23.50.28.png"
   }
}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

StatusCode 500 - Internal Server Error

Descripción de propiedades

Fields	Type	Comentario
id	Integer	Identificador del mensaje
did	String	Numero Whatsapp
msisdn	String	Numero Whatsapp del cliente
content	String	Max 3000 caracteres

Envío de multimedia

Servicio que permite enviar archivos multimedia (imágenes en JPG hasta 5 megas, PDF, Word, Excel y PPT hasta 20 megas) una vez que se ha generado el envío de HSM y el cliente ha dado respuesta al mensaje. Cuando el cliente responde un HSM se abre una sesión de 24 horas para realizar una conversación, se requiere integrar la siguiente estructura:

Path:

POST: /inbound/attach

Request
- Header:

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

Body

  {
   "id": "<identificador>",
   "did": "<identificador del canal>",
   "msisdn": "<identificador del destino>",
   "type": "media",
   "channel": "WHATSAPP",
   "content": "<contenido del mensaje>",
   "isAttachment": true,
   "attachment": {
           "mediaUrl": "<url del multimedia>",
           "mimeType": "<tipo del multimedia>",
           "base64": "<multimedia encoded base64>",
           "fileName": "<NombreDelFichero.jpg>"
       }
  }

Campo	Descripción
id	Identificador
did	Nro Whatsapp
msisdn	Nro Whatsapp del cliente
content	Max 3000 caracteres

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

StatusCode 500 - Internal Server Error

Envio de notificación

Cada mensaje que se envía por medio de esta API, es posible notificar los eventos de Whatsapp a un servicio que pueda proveer el cliente, considerando la siguiente estructura:

Path:

POST /{URL https entregada por el cliente}

Header:

   ["Authorization" : "Bearer <JWT>"] //Opcional

Body

{
   "id": "<identificador>",
   "did": "<identificador del canal>",
   "msisdn": "<identificador del destino>",
   "type": "SENT|DELIVERY|READ|ANSWER|INVALID|SESSION",
   "channel": "WHATSAPP",
   "timestamp": "20193940560",
   "answer": "true|false",
   "nodo": "RECHAZO_TDC"
}

Object Notify

Fields	Type	Mandatory	Descripción
id	Integer	yes	Identificador del mensaje, para el type “SESSION” el id es interno de Chattigo
did	String	yes	Número whatsapp asociado al envío HSM
msisdn	String	yes	Número de contacto del cliente
type	String	yes	Especifica el tipo de notificación generada
channel	String	yes	Indica el canal que se está realizando la transacción
timestamp	String	yes	Fecha del evento
answer	boolean	no	Indica la respuesta de la alerta de fraude
nodo	String	no	Indica el nodo desde donde se origina la respuesta , aplica sólo para BOT

Type Enum

SENT	Indica que el mensaje fue enviado (un check)
DELIVERY	Indica que el mensaje fue entregado al cliente (doble check)
READ	Indica que el mensaje fue leído por el cliente (doble check azul)
ANSWER	Indica la respuesta del cliente a una alerta definida, aplica sólo para BOT
SESSION	Indica que existe ventana de 24 horas para enviar outbound sin HSM
INVALID	Indica que el número de teléfono no es válido o no posee whatsapp

Envío Masivo de Mensajes Multimedia con Plantilla

Para el envío masivo de mensajes multimedia se requiere de un template autorizado por Facebook, el template debe ser habilitado en la plataforma. Al momento del envío se requiere integrar la siguiente estructura:

Es importante NO usar este método pa el envío de mensajes masivos

Path:

POST /inbound

Request
- Header:

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

Body

{
  "id": "1111111",
  "did": "234235325532",
  "type": "HSM",
  "channel": "WHATSAPP",
  "messageTemplate": {
    "destinations": [
      {
        "destination": "333333333333"
      }
    ],
    "namespace": "311a2215_7e0d_4664_b597_999847630f2",
    "botAttention": false,
    "name": "template_name",
    "language": {
      "policy": "deterministic",
      "code": "es"
    },
    "components": [
      {
        "type": "header",
        "sub_type": "document",// text | image | video | document | payload | location
        "parameters": [
          {
            "type": "document",// text | image | video | document | payload | location
            "value": { // Se especifica cuando type = image | video | document
              "link": "https://media.chattigo.com/files/media/storage/this-is-an-archive..pdf"
            },
            "location": { // Se especifica solo cuando type = location
              "latitude": "<latitude>",
              "longitude": "<longitude>",
              "name": "location name",
              "address": "location name"
            },
            "payload": "button text" // Se especifica cuando type = payload y el componente en un boton (type = button)
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "text_value"
          }
        ]
      }
    ]
  }
}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Descripcion de propiedades

Fields	Type	Comentario
did	String	Número de Whatsapp asociado al envío HSM
type	String	Valor no modificable
channel	String	Valor no modificable
destination	String	Número de teléfono que recibirá el mensaje (el código de país y DDD son obligatorios). Debe ir sin el símbolo “+” y completamente junto. Ejemplos: 5519900001111, 56999000222
namespace	String	ID del namespace que será usado. NOTA: Los parámetros namespace y name deben corresponder al Business Manager al cual el número de origen está asociado, o el mensaje tendrá una falla en el envío
botAttention	Boolean	Indica si el mensaje es atendido por un BOT
name	String	Nombre del Template registrado y aprobado
policy	String	Valor no modificable
code	String	Códigos: pt_BR, en, es, en_US, en_GB, pt_PT, es_AR, es_ES, es_MX, it, fr
type	String	Valor no modificable
sub_type	String	document / image / video
type	String	document / image / video (se repite el sub_type)
link	String	URL del archivo multimedia. Usar únicamente con URLs HTTP/HTTPS. El recurso debe contenter en su cabecera el “Content-Type”, a fin determinar el tipo de contenido será retornado
filename	String	Nombre que se le desea dar al archivo multimedia
parameters	Array	Lista de parámetros que serán reemplazados en el texto del template (solo en el caso de tenerlos). El arreglo de objetos debe mantener el formato tal como se muestra en el archivo json de ejemplo

Envío Masivo de Mensajes Templates Catálogos de un solo producto

Para el envío massivo de mensajes del tipo catálogo que contengan un solo producto debes tener el inventario subido a Meta en un catálogo de comercio electrónico conectado a tu cuenta comercial de WhatsApp.

Path:

POST https://shark-dev.chattigo.com/message/inbound

Request
- Header:

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

Body

{
  "id": "id",
  "did": "did",
  "channel": "WHATSAPP",
  "hsm": {
    "destinations": [
      {
        "destination": "DESTINATION"
      }
    ],
    "productsParameters": [
      {
        "type": "action",
        "action": {
          "thumbnail_product_retailer_id": "THUMBNAIL_PRODUCT_RETAILER_ID"
        }
      }
    ],
    "template": "template_name",
    "botAttention": false,
    "offlineAssignment": false,
    "attends": {
      "attend": 3,
      "assignedAgent": 0,
      "botType": 0,
      "waitTime": -1,
      "typification": 0
    }
  }
}

Response

Status Code 200

{
    "success": true
}

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Envío Masivo de Mensajes Templates Catálogos de varios productos

Los mensajes de plantilla de mensajes sobre varios productos deben incluir lo siguiente:

Un componente de encabezado (solo es obligatorio si la plantilla utiliza una variable de encabezado)
Un componente de cuerpo (solo es obligatorio si la plantilla utiliza una variable de cuerpo)
Un único componente de botón de mensajes sobre varios productos

Path:

POST https://shark-dev.chattigo.com/message/inbound

Request
- Header:

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

Body

{
  "id": "ID",
  "did": "DID",
  "channel": "WHATSAPP",
  "hsm": {
    "destinations": [
      {
        "destination": "DESTINATION DID"
      }
    ],
    "productsParameters": [
      {
        "type": "action",
        "action": {
          "thumbnail_product_retailer_id": "THUMBNAIL_PRODUCT_RETAILER_ID",
          "sections": [
            {
              "title": "<TITLE>",
              "product_items": [
                {
                  "product_retailer_id": "<PRODUCT_RETAILER_ID>"
                },
                ... // otros objetos item con su respectivo "product_retailer_id" (hasta 30)
              ]
            }
          ]
        }
      }
    ],
    "template": "template_name",
    "botAttention": false,
    "offlineAssignment": false,
    "attends": {
      "attend": 3,
      "assignedAgent": 0,
      "botType": 0,
      "waitTime": -1,
      "typification": 0
    }
  }
}

Response

Status Code 200

{
    "success": true
}

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Obtención de catálogos

Obtiene los catálogos por did, se debe introducir pasar el path param {did}

Path:

GET https://shark-dev.chattigo.com/message/catalogs/{did}

Request
- Header:

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

Response

Status Code 200

{
  "data": [
    {
      "id": "id",
      "name": "name"
    }
  ]
}

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Obtención de productos dentro de los catálogos

Obtiene productos de un catalogo , se debe introducir pasar el path param {did}

Se pueden adicionar los siguientes filtros como “query param”

clientId
catalogId
productId
deleted
name
description
brand
active
inventory
availability
condition
returnTotalElements
retailers
color
currency
category
gender
visibility
inOffer
updateHash
page number
size number

Path:

GET https://shark-dev.chattigo.com/message/catalogs/{did}/products?size=1

Request
- Header:

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

Response

Status Code 200

{
  "content": [
    {
      "clientId": 6,
      "id": "id",
      "name": "ceviche",
      "availability": "in stock",
      "category": "Food & Beverages",
      "currency": "PEN",
      "description": "ceviche descripción",
      "inventory": 100,
      "price": "S/30,00",
      "url": "https://ilcb.edu.pe/blog-detalle/el-lomo-saltado",
      "condition": "new",
      "Visibility": "published",
      "UpdateHash": "86763632",
      "retailer_id": "okxspqrepd",
      "image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t45.5328-4/355102886_5758501117587905_9004986909610399572_n.jpg?_nc_cat=109&ccb=1-7&_nc_sid=c7e7b7&_nc_ohc=wQN4Vrx7Bk0AX-uCJu2&_nc_ht=scontent-iad3-2.xx&edm=ANyJclEEAAAA&oh=00_AfAMPH9AZoKc-HTgw4TJCU3KpIn5hmYkxviA4mgH3pMlBQ&oe=65D282E7",
      "retailer_product_group_id": "m7ld4y6fn6",
      "product_catalog": {
        "id": "id",
        "name": "name"
      }
    }
  ]
}

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized

Envío Masivo de Flows con Plantilla

Para realizar un envio massivo de un flow se debe tener enviar lo siguiente:

Path:

POST /inbound

Request
- Header:

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

Body

{
  "id": "12",
  "did": "56940581384",
  "channel": "WHATSAPP",
  "hsm": {
    "totalContactToSend": 1,
    "destinations": [
      {
        "destination": "56978949142"
      }
    ],
    "template": "prueba_flow_1",
    "botAttention": false,
    "offlineAssignment": false,
    "attends": {
      "attend": 3,
      "assignedAgent": 0,
      "botType": 0,
      "waitTime": -1,
      "typification": 0
    }
  }
}

Response

Status Code 200

Errors

StatusCode 400 - Bad Request

StatusCode 401 - Unauthorized