Servicios Web para gestionar Webhooks

Servicios Web para gestionar Webhooks

Webhooks

/webhook/webhooks

Los webhooks son devoluciones de llamada HTTP definidas por el usuario que se activan mediante eventos específicos. Siempre que ocurre ese evento desencadenante, el cliente de la API de WhatsApp Business, recopila los datos e inmediatamente envía una notificación (solicitud HTTP) a la URL del webhook especificada en el endpoint de los webhooks que indica cuándo recibe un mensaje o se actualiza el estado de un mensaje enviado.

Este documento cubre:
  1. Pre-requisitos
  2. Solicitudes
    1. Crear
    2. Obtener
    3. Actualizar
    4. Borrar
  3. Respuestas de error
  4. Formato del webhook
    1. Mensaje de texto
    2. Alerta

Pre-requisitos

  1. Cuenta de Woztell activada
  2. Para usar la API de Woztell, debes primero autenticarte y recibirás un token que te permite acceder al servicio. Contacta con support@woztell.com para más información sobre cómo hacerlo.

Solicitudes

Cuando un cliente te envía un mensaje, la API de cliente de Woztell enviará una notificación de solicitud HTTP POST a la URL del Webhook con los detalles que se describen en el siguiente documento.
Es importante que tu Webhook devuelva una respuesta HTTPS 200 OK a las notificaciones. Si no es así, la API de cliente de Woztell considerará que la notificación ha fallado y no lo intentará de de nuevo.

Endpoint:

Parámetros:

Nombre de parámetro

Tipo de dato

Descripción

Posibles Valores

WOZTELL_ADMIN*

String

Dirección de email de tu cuenta de Woztell

admin@company.com

WOZTELL_TOKEN*

String

Tu token de la cuenta de Woztell

abc-defgh-ijk-123

WOZTELL_NUMBER*

String

Número de teléfono Woztell validado por WhatsApp.

"+1-631-555-1002", "16315551002", "001(631)555-1002"or "1 631 555 1002" 

DATA
JSON
Mira la siguiente documentación en la sección Parámetros de Datos

*Parámetro requerido

Crear

Crear un nuevo webhook
POST https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
	"WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
         "URL":"notifications-webhook-url",
         "LABEL":"your-label-text",
         "ENABLED":"boolean",
         "MESSAGES":"boolean",
         "ALERTS":"boolean"
  }
}      

Parámetros de DATOS:

Nombre del parámetro

Tipo de dato

Descripción

Posibles Valores

URL*

String

La URL de Webhook para enviar mensajes

"https://myserver.com/webhook"

LABEL*

String

Una etiqueta identificar rápidamente este webhook

"Zoho Flow notification"

ENABLED
Boolean
Si el Webhook está activo. El valor por defecto es true
true or false
MESSAGES
Boolean
Si quieres recibir los mensajes entrantes de texto en el Webhook. El valor por defecto es True
true or false
ALERTS
Boolean
Si quieres recibir las alertas de los mensajes salientes. El valor por defecto es false
true or false
IMAGES
Boolean
Si quieres recibir las imágenes entrantes. El valor por defecto es false
true or false
 *Parámetro requerido

Respuesta

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Obtener

Obtener un webhook
GET https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
           "ID":"webhook-id"
  }
}

Parámetros de DATOS:

Nombre de parámetro

Tipo de dato

Descripción

Posibles Valores

ID

String

Webhook ID. Si el ID no está especificado, todos los webhooks serán devueltos

"123123413" 

Respuesta

{
 "STATUS":"SUCCESS",
 "DATA":[
	{
            "ID":"webhook-id",
            "URL":"notifications-webhook-url",
             "LABEL":"your-label-text",
            "ENABLED": boolean,
            "MESSAGES": boolean,
            "ALERTS": boolean
  },
{

               "ID":"webhook-id",
               "URL":"notifications-webhook-url",
              "LABEL":"your-label-text",
              "ENABLED":"boolean",
               "MESSAGES":"boolean",
               "ALERTS":"boolean"
  },...
	]
}

Actualización

Actualizar un webhook
POST https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
      "ID" : "webhook-id"
      "URL":"notifications-webhook-url",
      "LABEL":"your-label-text",
      "ENABLED":"boolean", 
      "MESSAGES":"boolean",
      "ALERTS":"boolean"
   }
}                              
Parámetros de DATOS:

Nombre de parámetro

Tipo de DATO

Descripción

Posibles valores

ID*

String

Webhook ID

"123123413"

URL

String

Tu token de la cuenta de Woztell

"https://myserver.com/webhook"

LABEL
String
Una pestaña para realizar el seguimiento de la finalidad de los webhooks
"Zoho Flow notification"
ENABLED
Boolean
Si el webhook está activo
True or false
*Parámetro requerido

Respuesta

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Borrar

Borrar un webhook
DELETE https://webservice.woztell.com/webhook/webhooks
{
 "WOZTELL_ADMIN":"your-woztell-admin-email",
 "WOZTELL_TOKEN":"your-woztell-token",
 "WOZTELL_NUMBER":"your-woztell-number",
 "DATA":
  {
   "ID":"webhook-id"
  }
}
Parámetros de DATOS:

Nombre de parámetro

Tipo de Dato

Descripción

Posibles valores

ID*

String

Webhook ID

"123123413"

*Parámetro requerido

Respuesta

{
 "STATUS":"SUCCESS",
 "ID":"webhook-id"
}

Respuestas de error

Consulta el siguiente documento para obtener más información sobre los siguientes tipos de mensajes de estado y error:

STADO

DESCRIPCIÓN

ERROR

             MÉTODO NO PERMITIDO

ERROR

             AUTORIZACIÓN NO VÁLIDA

ERROR

             JSON DATA NO VÁLIDO

ERROR

             WHATSAPP NO ACTIVADO

ERROR

             Otros detalles del error

{
      "STATUS":"ERROR",
      "DESCRIPTION":"INVALID JSON DATA"
   }

Formato de las notificaciones Webhook

Mensajes
Cuando un cliente te envía un mensaje, la API de cliente de Woztell enviará una notificación de solicitud HTTP POST a la URL del Webhook en el siguiente formato:
{
        "id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"text",
	"timestamp":"timestamp-for-WhatsApp-message",
	"text":"text-WhatsApp-message"
}            
Parámetros:

Nombre del parámetro

Tipo de dato

Descripción

Posibles Valores

ID

String

ID del mensaje de WhatsApp

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from
String
Número de WhatsApp del emisor en formato internacional
"0019875632588"
to
String
El número de WhatsApp del destinatario
"0034675572588"
type
String
Tipo de mensaje. "text" is the only possible value.
"text"
timestamp
Number
Hora en que fue enviado el mensaje. La marca de tiempo es en segundos
"1593554400"
text
String
Mensaje de texto de WhatsApp
"Hello world"


Alertas

Cuando envías un mensaje a un número de teléfono, la API de cliente de Woztell enviará una notificación de solicitud HTTP POST a la URL del Webhook en el siguiente formato:
{
 	"id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"alert",
	"timestamp":"timestamp-for-WhatsApp-message",
	"status":"WhatsApp-message-status",
	"error":"WhatsApp-error-message"
}
Parámetros:

Nombre de parámetro

Tipo de dato

Descripción

Posibles valores

ID

String

ID del mensaje de WhatsApp

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from
String
Número de WhatsApp del emisor en formato internacional
"0019875632588"
to
String
El número de WhatsApp del destinatario
"0034675572588"
type
String
Tipo de solicitud. "alert" es el único valor posible.
"alert"
timestamp
Number
Hora en que la alerta fue recibida. Marca de tiempo en segundos.
"1593554400"
status
String
Estado de mensaje de WhatsApp. Indica el estado del mensaje de WhatsApp
Verifica los tipos de estado en el siguiente punto
error
string
Razón del error indicado por WhatsApp
https://developers.facebook.com/docs/whatsapp/api/errors

Tipos de estado

  • "send": el servidor ha recibido el mensaje que ha enviado su empresa.

  • "delivered": el mensaje que envió tu empresa fue enviado al dispositivo del usuario.

  • "read": el usuario leyó el mensaje enviado por tu empresa. Las notificaciones de lectura solo están disponibles para los usuarios que tienen habilitada la confirmación de lectura. Los usuarios que no lo tengan habilitado, solo recibirán la notificación de entrega.

  • "failed": el mensaje enviado por tu empresa no pudo ser enviado. En el campo error recibirá el motivo.

Imágenes
Cuando un cliente te envía una imágen, la API de cliente de Woztell enviará una notificación de solicitud HTTP POST a la URL del Webhook en el siguiente formato:
{
        "id":"WhatsApp-message-id",
	"from":"from-WhatsApp-phone",
	"to":"to-WhatsApp-phone",
	"type":"image",
	"timestamp":"timestamp-for-WhatsApp-message",
	"base64":"base64-image-encode",
            "mimeType":"mimeType-image",
            "caption":"image-comment"
}            
Parámetros:

Nombre del parámetro

Tipo de dato

Descripción

Posibles Valores

ID

String

ID del mensaje de WhatsApp

"ABGHVJNHZYFRPwIQtAkyZ4zvbaRCCwqa1ekDuQ"

from
String
Número de WhatsApp del emisor en formato internacional
"0019875632588"
to
String
El número de WhatsApp del destinatario
"0034675572588"
type
String
Tipo de mensaje. "image" es el único valor posible.
"image"
timestamp
Number
Hora en que fue enviado el mensaje. La marca de tiempo es en segundos
"1593554400"
base64String
Codificación de la imagen en base64
"......................"

mimeType
String
Formato de la imagen. Valores posibles: "image/png" o "image/jpeg"
"image/png"
caption
String
Comentario que acompaña la imagen.
"Esto es un comentario"