API OFICIAL BSP (MESSAGES)

Comunicate con tus clientes a través de API Cloud.

API Cloud

En comparación con las soluciones anteriores, Cloud API es más fácil de usar y es una forma más rentable para que las empresas usen WhatsApp. La API en la nube brinda grandes beneficios en comparación con la API local de WhatsApp.

Mensajería

Novedades

Sin necesidad de actualizaciones, las funciones disponibles en API Cloud:

Almacenamiento en caché de enlaces multimedia mejorado

Para los envíos de mensajes multimedia mediante enlaces, la API Cloud ahora es compatible con el protocolo de almacenamiento en caché HTTP. Esto permite a las empresas establecer sus opciones de almacenamiento en caché preferidas y comunicarlas con API Cloud mediante la configuración de encabezados HTTP relevantes

La reducción para la política de reintentos de Webhook

API Cloud llama al Webhook empresarial para notificar a la empresa sobre entregas, lecturas y respuestas de mensajes. Si el Webhook está inactivo por algún motivo, API Cloud vuelve a intentar notificar al Webhook durante un máximo de 7 días.

Nuevo punto de conexión de archivos multimedia que verifica los permisos de propiedad

Introduce un nuevo parámetro de consulta para verificar la propiedad de los archivos a nivel de número de teléfono, para diferenciar los tipos que pertenecen a un número de teléfono específico.

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

Debe crear una plantilla de mensaje antes de poder enviar una. Puede consultar a nuestro equipo para un asesoramiento en ese caso.

Se pueden enviar diversos tipos de mensajes:

Mensajes de Plantilla
Mensajes de texto
Mensajes de contenido multimedia
Mensajes de reacción
Mensajes de ubicación
Mensajes de contacto
Mensajes interactivos

Para enviarlos, realice una llamada POST /{version}/{did}/messages y adjunte un objeto de mensaje con el tipo que desee. Luego, agregue un objeto que corresponda con ese tipo y proceda al envío. Para más información remitirse a documentación de Meta

A continuación exponemos un ejemplo de body para los 3 primeros casos antes expuestos:

La ruta POST /v15.0/{did}/messages será la encargada de enviar un mensaje para ello se debe enviar un Header de la siguiente manera:

  ["Authorization" : "<JWT>"]

Definición de Objeto

Fields	Type	Mandatory	Descripción
did	String	yes	identificador del canal

Plantillas

Para el caso del envío de plantillas se debe enviar 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 se debe enviar 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 del envío de mensajes de multimedia se debe enviar 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 enviar los tipos audio, document, image, sticker o video, para todos los casos solo se le debe cambiar el type de mensaje a enviar y la key en el payload.

A partir de la version 17 y 18 de api-cloud es posible enviar flows por medio de un mensaje iterativo o plantilla

Envío de flow como mensaje iterativo

{
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
        "flow_id": "1",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_NAME>",
          "data": { 
            "product_name": "name",
            "product_description": "description",
            "product_price": 100
          }
        }
      }
    }
  }
}

Envío de flow como template

{
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
        "flow_id": "1",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_NAME>",
          "data": { 
            "product_name": "name",
            "product_description": "description",
            "product_price": 100
          }
        }
      }
    }
  }
}

Para todos los casos en la mensajería la respuesta satisfactoria será como la siguiente, nótese que siempre se devolverá un objeto con un identificador con wamid como prefijo identificador del mensaje recién enviado:

   {
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "48XXXXXXXXX",
      "wa_id": "48XXXXXXXXX "
    }
  ],
  "messages": [
    {
      "id": "wamid.gBGGSFcCNEOPAgkO_KJ55r4w_ww"
    }
  ]
}

Adjuntos

La ruta GET /v15.0/{id}/{did}/media será la encargada de devolver un archivo multimedia para ello se debe enviar un Header de la siguiente manera:

   ["Authorization" : "<JWT>"]

Webhook cliente

La ruta PATCH /webhooks/inbound será el servicio para agregar o cambiar el endpoint que permitirá la recepción de los mensajes inbound de cliente, 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>",
  "externalWebhook": "<URL segura HTTPS>"
}

Definición de Objeto

Fields	Type	Mandatory	Descripción
waId	String	yes	identificador del canal
externalWebhook	String	yes	URL del cliente que permite el despacho de mensajes inbound

Response

StatusCode 200

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

Cuerpo del mensaje a recepcionar:

Para el caso de los mensajes inbound Chattigo le enviará a su webhook un payload como el que se encuentra en la documentación de Meta

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

Envio de Mensajes

POST /{did}/messages

400 (Payload incorrecto)

{
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Recipient phone number not in allowed list: Add recipient phone number to recipient list and try again."
    },
    "error_subcode": 2655007,
    "fbtrace_id": "AhmxnHaQX1B1ZJX8g8n_hMW"
  }
}

400 ({did} incorrecto)

{
  "message": "unsupported get request. Object with ID ‘{bad-did}’ does not exist, cannot be loaded due to not belonging to your campaigns, or does not support this operation, Please read the API documentation at https://development.chattigo.com"
}

Descarga de adjuntos

POST /{id}/{did}/media

400 ({did} incorrecto)

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

400 ({id} incorrecto)

{
  "error": {
    "message": "Unsupported get request. Object with ID '888957019219789-1' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api",
    "type": "GraphMethodException",
    "code": 100,
    "error_data": {
      "messaging_product": "",
      "details": ""
    },
    "error_subcode": 33,
    "fbtrace_id": "AwHpFmcgxcs-z-cHjld1N8A"
  }
}

PATCH /webhooks/inbound

400 (waId incorrecto en el payload de entrada)

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

Para mas información se puede remitir al apartado de errores de Meta.