Documentación de WhatsApp Access API

En la actualidad, más de 1.500 millones de personas en más de 180 países utilizan WhatsApp para mantenerse en contacto con sus amigos y familiares, en cuaquier lugar y en cualquier momento. Las empresas de todo el mundo ya han comenzado a utilizar WhatsApp de manera informal para comunicarse con sus clientes, ya sea sobre consultas de productos o actualizaciones de transacciones. El API de WhatsApp Business es una nueva manera en que las empresas pueden mejorar el manejo de estas conversaciones con sus clientes y llegar a otros nuevos que también valorarán la experiencia de mensajería instantánea rápida, cómoda y privada.

Esta guía proporciona las especificaciones de las API de Gupshup para enviar y recibir mensajes en WhatsApp a través de un API REST sencillo mediante los modos HTTP/HTTPS.

Establecer la URL del Webhook/Callback

Los Webhooks gestionan los mensajes entrantes de las personas que te responden en WhatsApp, incluyendo texto, ubicación y multimedia tal como imágenes y documentos, así como el estado de los mensajes que has enviado. Los Webhooks son esenciales ya que se utilizan para entregar notificaciones oportunas y errores out-of-band (OOB) , y es por lo tanto, muy recomendable que configures uno en los ajustes de la aplicación.

Los mensajes entrantes enviados por los clientes a tu número de teléfono de WhatsApp Business se enviarán a tu Webhook, es decir, cuando un cliente envía un mensaje de texto o un archivo multimedia adjunto en WhatsApp, la plataforma de Gupshup registra el evento e inmediatamente envía una notificación (solicitud HTTP POST) al Webhook especificado en la configuración de tu aplicación. Algunos puntos importantes acerca de Webhook:

1. El Webhook debería devolver HTTP_SUCCESS (code: 2xx) con una respuesta vacía. Si no lo hace en 10 segundos, consideraremos que la notificación ha fallado y lo intentaremos de nuevo después de un breve período.
2. Tu Webhook debería procesar mensajes y eventos entrantes de forma asíncrona, pero confirmar su recepción de forma sincrónica e inmediata. El mejor tiempo de confirmación debería ser menor a 100 milisegundos, y dado que cierto retraso en la red es comprensible, se recomienda que sea de 500 a 1000 milisegundos. Cuanto mayor sea el tiempo de respuesta, mayor será el retraso de los mensajes y eventos entrantes que recibirás en cada ocasión.
3. El Webhook debería aceptar el encabezado HTTP: User-Agent User-Agent
4. El Webhook debería aceptar el evento de usuario: sandbox-start
5. El Webhook debería tener acceso público, y si por razones de seguridad quieres mantenerlo privado, es necesario que pongas en lista blanca las IPs de solicitud de entrada de Gupshup. Contáctanos en devsupport@gupshup.io para obtener estas IPs.

Consulta la imagen a continuación para localizar la opción de establecer Webhook/Callback en la configuración de la app. Si la opción de URL de devolución de llamada está desactivada, podrás ver los mensajes entrantes en Mensajes Entrantes | Eventos el campo. Estos mensajes y eventos registrados se almacenan temporalmente, lo que significa que se borran si se actualiza la página.

Mensajes entrantes y eventos

Los tres tipos de notificaciones entrantes entregadas a tu Webhook son:

1. usuario-evento
2. eventos-del sistema
3. mensaje-evento
4. billing-evento
5. mensaje

Parámetros/Propiedades comunes a todas las notificaciones entrantes

{
  "app": "DemoApp",
  "timestamp": 1580227766370,
  "version": 2,
  "type": "user-event"|"template-event"|"message-event"|"message",
  "payload": << Varia según el valor de la propiedad - "type" >>
}

Evento

En esta sección entenderemos:
1.  Evento de usuario: Estos son generados por nuestra plataforma cuando ocurre algún evento. Por ejemplo, recibirás los siguientes eventos del sistema cuando:
-Una URL de devolución de llamada es establecida para una app o mientras se utiliza el comando proxy para ejecutar tu app en el número de teléfono del bot del Proxy de Gupshup (+917834811114) para probar la aplicación.
– Un usuario final da su consentimiento (Opt-in) para recibir notificaciones de un número de teléfono comercial.

{
   "app":"DemoApp",
   "timestamp":1580142086287,
   "version":2,
   "type":"user-event",
   "payload":{
      "phone":"callbackSetPhone"|"918x98xx21x4",
      "type":"sandbox-start"|"opted-in"|"opted-out"
   }
}

El objeto del payload

El tipo de usuario-evento

2.  eventos del sistema : Estos son generados por nuestra plataforma cuando ocurre algún evento. Puedes elegir recibir estos eventos en tu URL de devolución de llamada desde la configuración del panel de control de la app. Por ejemplo, los siguientes eventos del sistema se reciben cuando:
– Se recibe un evento del sistema de tipo plantilla cuando se actualiza el estado de la plantilla. Por ejemplo, una plantilla enviada ha sido aprobada o rechazada.
– Se recibe un evento del sistema de tipo cuenta. Por ejemplo, cuando se actualiza el estado del número de teléfono o del nombre para mostrar de un WABA.
Los eventos del sistema se clasifican en dos tipos:

{
«app»: «jeet20»,
«timestamp»: 1636986446609,
«version»: 2,
«type»: «template-event»,
«payload»:{ «id»: «4dacef15-6c04-12db-b393-6190ac567eff», «status»: «REJECTED/APPROVED/DELETED/DISABLED», «elementName»: «abcd», «languageCode»: «en_US», «rejectedReason»: «INAVLID_FORMAT» }
}

El objeto del payload

• Eventos de cuenta
  Los eventos de cuenta se reciben cuando se produce un evento en una WABA específica. Por ejemplo, cuando una WABA incumple una política empresarial de WhatsApp, o si se actualiza el límite de nivel de mensajería de una WABA.

Los tipos de eventos de cuenta y sus objetos de payload son los siguientes:

3.  Evento de mensaje : Estos eventos indican el estado del mensaje enviado mediante la API de envío de mensajes al cliente de la API de WhatsApp (que básicamente envía un mensaje al usuario). El cliente de la API de WhatsApp Business enviará notificaciones para informar el estado de los mensajes entre los usuarios y tu. Cuando un mensaje se envíe con éxito, recibirás una notificación de cuándo se ha enviado, entregado y leído. El orden de estas notificaciones en tu app puede no reflejar el momento real del estado del mensaje. Consulta la marca de tiempo para determinar el momento, si es necesario. Las notificaciones que podrías recibir son:

{
«app»:»DemoAPI»,
«timestamp»:1580546677791,
«version»:2,
«type»:»message-event»,
«payload»:{
«id»:»59f8db90-c37e-4408-90ab-cc54ef8246ad»(identificador de mensaje de Gupshup)|»gBEGkYaYVSEEAgnZxQ3JmKK6Wvg» (identificador de mensaje de WhatsApp)
«gsId»: «ee4a68a0-1203-4c85-8dc3-49d0b3226a35» (ID de mensaje de Gupshup: esta propiedad solo se aplica a eventos de DLR)
«type»:»enqueued»|»failed»|»sent»|»delivered»|»read»,
«destination»:»91XX985XX10X»,
«payload»: << Varia según el valor de la propiedad – «type» >>;
}
}

El objeto de payload

4.  billing-event : evento de billing se activa solo cuando una conversación es facturable. Para conversaciones gratuitas, no recibirá un evento de billing.

{
«app»: «DemoAPI»,
«timestamp»:1580546677791,
«version»:2,
«type»: «billing-event»,
«payload»:{
«deductions»:{
«type»: «FEP/UIC/BIC»,
«model»: «NBP/CBP»,
«source»: «whatsapp»
},
«references»:{
«id»:»59f8db90c37e-4408-90ab-cc54ef8246ad»,
«gsId»:»ee4a68a0-1203-4c85-8dc3-49d0b3226a35″,
«conversationId»:»532b57b5f6e63595ccd74c6010e5c5c7″,
«destination»:»91XX985XX10X»
}
}
}

Descripción del objeto de las deduction

References objeto descripción

Motivo del fallo del mensaje con respecto al código de error:

Para saber más sobre los códigos de error del cliente de la API de WhatsApp Business, haz clic aquí

Mensaje entrante

En esta sección, entenderemos el evento: los mensajes que recibes en la URL de devolución de llamada. Este evento indica el tipo de payload del mensaje recibido en tu URL de devolución de llamada cuando un cliente envía un mensaje al número de teléfono registrado en la API de WhatsApp Business.

Headers

Parámetros/propiedades comunes a todos los mensajes entrantes

{
«app»: «DemoApp»,
«timestamp»: 1580227766370,
«version»: 2,
«type»: «message»,
«payload»: {
«id»: «ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c»,
«source»: «918x98xx21x4»,
«type»: «text»|»image»|»file»|»audio»|»video»|»contact»|»location»|»button_reply»|»list_reply»,
«payload»: {
//Varía según el tipo de payload
},
«sender»: {
«phone»: «918x98xx21x4»,
«name»: «Smit»,
«country_code»: «91»,
«dial_code»: «8x98xx21x4»
},
«context»: {
«id»: «gBEGkYaYVSEEAgnPFrOLcjkFjL8»,
«gsId»: «9b71295f-f7af-4c1f-b2b4-31b4a4867bad»
}
}
}

El objeto del payload

El objeto de remitente

El objeto de contexto

Veamos uno por uno los tipos de mensajes entrantes recibidos en la URL de devolución de llamada:

Text

A continuación se muestra un ejemplo de payload cuando un cliente envía un mensaje de texto en WhatsApp al número de su empresa.

{ 
  "app": "DemoApp", 
  "timestamp": 1580227766370,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",   
    "source": "918x98xx21x4",   
    "type": "text", 
    "payload": {    
      "text": "Hi"  
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}

Un cliente responde a un mensaje comercial

Los usuarios pueden responder a un mensaje específico en WhatsApp. Para que la empresa comprenda el contexto de la respuesta de un mensaje, incluimos el objeto de contexto. Este objeto proporciona el identificador de mensaje de Gupshup(property: gsId) del mensaje al que el cliente ha respondido y el identificador de mensaje de WhatsApp(property: id) del mensaje original.

{
  "app": "DemoApp",
  "timestamp": 1590854464792,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
    "source": "918x98xx21x4",
    "type": "text",
    "payload": {
      "text": "hi"
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
      "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
      "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
    }
  }
}

El cliente hizo click en el botón de mensaje de una plantilla de respuesta rápida

Cuando un cliente selecciona un botón de mensaje de respuesta rápida, se recibe el siguiente ejemplo de payload.
Para que la empresa comprenda el contexto de la respuesta de un mensaje, incluimos el objeto de contexto. Este objeto proporciona el identificador de mensaje de Gupshup(property: gsId) del mensaje al que el cliente ha respondido y el identificador de mensaje de WhatsApp(property: id) del mensaje original. Además, el objeto de payload proporciona el texto del botón que el usuario ha pulsado.

{
  "app": "DemoApp",
  "timestamp": 1590854464792,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
    "source": "918x98xx21x4",
    "type": "text",
    "payload": {
      "text": "View Account Balance",
      "type": "button"
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
      "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
      "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
    }
  }
}

Multimedia

Cuando se recibe un mensaje con multimedia (imagen | documento | audio | video | sticker), el cliente de la API de WhatsApp Business descargará el contenido. Una vez descargado, se envía una notificación a nuestra plataforma, es decir a tu Webhook. Este mensaje contiene información que identifica el objeto multimedia y te permite encontrar y descargar el objeto.

Payload de contenido multimedia

Imagen

A continuación se muestra un ejemplo de payload recibido cuando un cliente envía una imagen junto con un título al número de la empresa. El título sólo está presente si se proporciona.

{   
  "app": "DemoApp", 
  "timestamp": 1580227895991,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhAE0dyndiP9cVlr4hC5xU64",   
    "source": "918x98xx21x4",   
    "type": "image",    
    "payload": {    
      "caption": "Sample image",    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/546af999-825e-485b-bf54-4a3323824cca",  
      "contentType": "image/jpeg",  
      "urlExpiry": 1624956794816    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Audio

A continuación se muestra un ejemplo de payload recibido cuando un cliente envía un archivo de audio o un mensaje de voz al número de teléfono de la empresa. En el caso de los mensajes de voz, el tipo de contenido es siempre: audio/ogg; codecs=opus

{   
  "app": "DemoApp", 
  "timestamp": 1580228104661,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhC8Sqz6bdT95X8wgVH28wz8",   
    "source": "918x98xx21x4",   
    "type": "audio",    
    "payload": {    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/eae8a65a-b3ec-4085-94a6-3738338835fc",  
      "contentType": "audio/ogg; codecs=opus",  
      "urlExpiry": 1624956864635    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Video

A continuación se muestra un ejemplo de payload recibido cuando un cliente envía un vídeo junto con un título al número de teléfono de la empresa.

{   
  "app": "DemoApp", 
  "timestamp": 1580228336953,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhDHMK-ctBQwqxyKoMbKcxES",   
    "source": "918x98xx21x4",   
    "type": "video",    
    "payload": {    
      "caption": "Sample video",    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/9f5ff20a-d14f-47ea-b336-754756a8b950",  
      "contentType": "video/mp4",   
      "urlExpiry": 1580833136954    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Document

A continuación se muestra un ejemplo de payload recibido cuando un cliente envía un documento junto con un título al número de teléfono de la empresa. El título sólo está presente si se proporciona.

{   
  "app": "DemoApp", 
  "timestamp": 1580228523976,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",   
    "source": "918x98xx21x4",   
    "type": "file", 
    "payload": {    
      "caption": "Document caption",    
      "name": "samplefile.pdf", 
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/b6e4e360-be01-4ffa-8928-84b8f40dd2eb",  
      "contentType": "application/pdf", 
      "urlExpiry": 1624957181122    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Sticker

A continuación se muestra un ejemplo de payload recibido cuando un cliente envía un sticker al número de teléfono de la empresa.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",
    "type": "sticker",
    "payload": {
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/32030cb2-68de-4c3c-a795-c4647fd4a9c7",
      "contentType": "image/webp",
      "urlExpiry": 1624957279044
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "John",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    }
  }
}

Mensajes interactivos

El cliente ha respondido a un mensaje de Lista

A continuación se muestra un ejemplo de payload que se recibe cuando un cliente selecciona y envía un artículo de la lista de mensajes al número de teléfono de la empresa.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",
    "type": "list_reply",
    "payload": {
            "title": "section 1 row 1",
            "id": "list1",
            "reply":"section 1 row 1 1",
            "postbackText":"section 1 row 1 postback payload",
            "description": "first row of first section description"
        },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "John",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
        "id": "gBEGkYaYVSEEAgnPGGVYGg1uNU4",
        "gsId": "cbdafe39-1023-42a7-89d6-6c01a3388bb5"
    }
  }
}

El cliente respondió a un botón de respuesta rápida

Cuando un cliente selecciona un botón de mensaje de respuesta rápida, se recibe el siguiente ejemplo de payload.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",   
    "type": "button_reply", 
    "payload": {    
            "title": "First",   
            "id": "qr1",    
            "reply":"First 1"   
        },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    },  
    "context": {    
        "id": "gBEGkYaYVSEEAgkvE0f1ZkfXX78",    
        "gsId": "123b0fb2-0620-493b-8f7e-5a1ceb6d8c58"  
    }   
  } 
}   

Otros mensajes

Ubicación

A continuación se muestra un ejemplo de carga útil recibida cuando un cliente comparte su ubicación con el número de la empresa.

Por favor considera que la ubicación en vivo no es un tipo de mensaje compatible con WhatsApp Business por el momento.

{   
  "app": "DemoApp", 
  "timestamp": 1580228767338,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhCIxTq7KXQIqby1Uo-IO7_E",   
    "source": "918x98xx21x4",   
    "type": "location", 
    "payload": {    
      "longitude": "72.8552172",    
      "latitude": "19.1453658"  
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Tarjeta de contacto

A continuación se muestra un ejemplo de payload recibido cuando un cliente comparte una tarjeta de contacto al número de la empresa.

{
  "app": "DemoApp",
  "timestamp": 1584898884710,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhD9cTZVyPlOGYZJOnviI7OJ",
    "source": "918x98xx21x4",
    "type": "contact",
    "payload": {
      "contacts": [
        {
          "addresses": [
            {
              "city": "Menlo Park",
              "country": "United States",
              "countryCode": "us",
              "state": "CA",
              "street": "1 Hacker Way",
              "type": "HOME",
              "zip": "94025"
            },
            {
              "city": "Menlo Park",
              "country": "United States",
              "countryCode": "us",
              "state": "CA",
              "street": "200 Jefferson Dr",
              "type": "WORK",
              "zip": "94025"
            }
          ],
          "emails": [
            {
              "email": "test@fb.com",
              "type": "WORK"
            },
            {
              "email": "test@whatsapp.com",
              "type": "WORK"
            }
          ],
          "ims": [

          ],
          "name": {
            "first_name": "Dev",
            "formatted_name": "Dev Support",
            "last_name": "Support"
          },
          "org": {
            "company": "Dev Support"
          },
          "phones": [
            {
              "phone": "+91 77383 05433",
              "type": "Mobile"
            }
          ],
          "urls": [
            {
              "url": "https://www.facebook.com",
              "type": "WORK"
            }
          ]
        }
      ]
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    }
  }
}

Referencia

Se incluye en las notificaciones cuando un usuario hace click en un anuncio que hace click en WhatsApp y envía un mensaje a la empresa. Este objeto tiene la información del anuncio.

{
    "app": "DemoApp",
    "timestamp": 1624350395531,
    "version": 2,
    "type": "message",
    "payload": {
        "id": "ABEGkZlpNARoAgo6v1b-zBR7EnX3",
        "source": "918x98xx21x4",
        "type": "text",
        "payload": {
            "text": "I saw this on Facebook..."
        },
        "sender": {
            "phone": "918x98xx21x4",
            "name": "Smit",
            "country_code": "91",
            "dial_code": "8x98xx21x4"
        },
        "referral": {
                "body": "Test post payload",
                "headline": "Demo Gupshup ad",
                "image": {
                    "id": "6a35b528-429d-4fe3-953d-536ef0397ece"
                },
                "source_id": "951242428775548",
                "source_type": "post",
                "source_url": "https://fb.me/2oNXGTsjn"
        }
    }
}

Mensaje de salida

Sesión de mensajería

Esta guía te enseña cómo enviar un mensaje de sesión a un cliente utilizando la API de envío de mensajes. Actualmente, este tipo de mensajería sólo puede realizarse dentro de las 24 horas siguientes al último mensaje enviado por el usuario. Si intentas enviar un mensaje fuera de la ventana de 24 horas, obtendrás un evento de fallo en tu Webhook. Para entender los estados del usuario en nuestra plataforma, por favor, consulta este artículo, esto te ayudará a utilizar la API de manera más eficaz.

Entendamos la especificación/firma de la API, es decir, el Endpoint de la API, los encabezados, el cuerpo de la solicitud y su respuesta en detalle:

API Endpoint

Para enviar un mensaje en WhatsApp, la solicitud de la API se hace al endpoint:

https://api.gupshup.io/sm/api/v1/msg

API Request

Solicitud de API de muestra

curl –location –request POST ‘https://api.gupshup.io/sm/api/v1/msg’ \
–header ‘Cache-Control: no-cache’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–data-urlencode ‘channel=whatsapp’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘message={«type»: «text»,»text»: «Hi John, how are you?»}’ \
–data-urlencode ‘src.name=DemoApp’ \
–data-urlencode ‘disablePreview=false’

Headers

El cuerpo de la solicitud

Arámetros de objetos de mensaje comunes

Enviar texto

A continuación se muestra un ejemplo de carga útil al enviar un mensaje de texto en WhatsApp.

– Un mensaje de texto puede tener un máximo de 4096 caracteres.
– Para incluir una vista previa de la URL en el mensaje y asegurarse de que comience con http:// o https://.
– Una URL a previsualizar: se requiere el nombre de host, no se tendrán en cuenta las direcciones IP.
– Si un mensaje de texto tiene múltiples URL, la primera URL sólo se previsualizará.

Opciones de formato

WhatsApp admite algunos formatos en los mensajes de texto. Para dar formato a todo o parte de un mensaje, utiliza estos símbolos de formato:

También se admiten los emoji. La lista de emoji compatibles se encuentra en https://emojipedia.org/whatsapp/. Copia el símbolo emoji en el mensaje de texto cuando lo envíes a través de la API.

Multimedia

Enviar mensaje de imagen

A continuación se muestra un ejemplo de carga útil al enviar una imagen en WhatsApp.

– Tipos de contenido admitidos: image/jpeg, image/png
– maximum file size: 5 MB

Enviar mensaje de documento / archivo

A continuación se muestra un ejemplo de carga útil al enviar un documento/archivo en WhatsApp.

– Tipos de contenido admitidos: Cualquier tipo MIME válido
– Tamaño máximo de archivo: 100 MB

Enviar mensaje de audio

A continuación se muestra un ejemplo de carga útil al enviar un archivo de audio en WhatsApp.

-Tipos de contenido admitidos: audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus. Note: No se admite el tipo de audio / ogg base.
– Tamaño máximo de archivo: 16 MB

Enviar mensaje de video

A continuación se muestra un ejemplo de carga útil al enviar un vídeo en WhatsApp.

– Tipos de contenido admitidos: video/mp4, video/3gpp. Note: Solo se admiten el códec de video H.264 y el códec de audio AAC.
– Tamaño máximo de archivo: 16 MB

Enviar Stickers

A continuación se muestra un ejemplo de carga útil al enviar un sticker en WhatsApp.

– Cada pegatina tiene un fondo transparente.
– Las pegatinas deben tener exactamente 512 x 512 píxeles.
– Cada pegatina debe tener menos de 100 KB.

Mensajes interactivos

Enviar mensajes de lista

Mensajes que incluyen un menú de hasta 10 opciones. Este tipo de mensaje ofrece una forma más sencilla y coherente para que los usuarios hagan una selección cuando interactúan con una empresa. A continuación se muestra un ejemplo de carga útil para enviar mensajes de lista al usuario final.

Envía respuestas rápidas

Este tipo de mensaje ofrece una forma más rápida de que los usuarios hagan una selección de un menú cuando interactúan con una empresa. Los botones de respuesta poseen la misma experiencia de usuario que las plantillas interactivas con botones.

A continuación se muestra un ejemplo de carga útil al enviar un mensaje de respuestas rápidas a los usuarios finales en WhatsApp.

Otros mensajes

Enviar mensaje de ubicación

A continuación se muestra un ejemplo de carga útil para enviar la ubicación estática al usuario final.

Enviar tarjeta de contacto

A continuación se muestra un ejemplo de carga útil para compartir una tarjeta de contacto con el usuario final.

Respuesta de la API

Las solicitudes de la API de envío de mensajes recibidas por nuestra plataforma se procesan de forma asíncrona, por lo que siempre obtendrás una respuesta HTTP_SUCCESS(200 to 299) si la solicitud de la API se realizó correctamente. La respuesta de la API incluye un objeto con un identificador de mensaje de Gupshup y un estado como enviado y el Webhook recibirá message-event que indica que el mensaje enviado al cliente de la API de WhatsApp (que realmente envía el mensaje al cliente) está en cola o ha fallado.

{"status":"submitted","messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"}

El identificador de mensajes de Gupshup, es decir messageId en la respuesta de la API, ayudará a rastrear los mensajes a través de los eventos, es decir, “enqueued”|“failed”|“sent”|“delivered”|“read” recibidos en el Webhook.

Plantilla de mensaje

Las plantillas de mensaje permiten a una empresa enviar notificaciones a sus clientes fuera del periodo de 24 horas. WhatsApp exige que las notificaciones sólo se envíen a los usuarios que hayan dado su consentimiento para recibir mensajes. Manteniendo esto como un comportamiento por defecto en nuestra plataforma, las plantillas de mensaje sólo pueden ser enviadas a los usuarios que están marcados como opt-in. Para marcar a un usuario como opt-in utiliza Mark User Opt-in API

Hemos estado recibiendo consultas de los usuarios de nuestra plataforma que se enfrentan a problemas para enviar plantillas de mensaje a su usuario final. Al analizar estos problemas, descubrimos que la mayoría de ellos estaban relacionados con la falta de coincidencia del mensaje con el de la plantilla aprobada. Por lo tanto, se ha lanzado una nueva API de mensajería de plantillas para reducir estos errores.

Esto no indica que la API genérica para enviar tanto mensajes de sesión como de plantilla sea obsoleta, esta se puede seguir utilizando. A continuación se muestra la API de mensajería de plantillas tradicional:

Al contrario de la API anterior, en la que se requiere enviar el cuerpo del mensaje completo con marcadores de texto y de posición, la nueva API de plantillas de mensajes sólo toma un id de plantilla y el valor de los marcadores de posición.

Entendamos la especificación/firma de la API, es decir, el Endpoint de la API, Encabezados, el Cuerpo de la Solicitud y la Respuesta en detalle:

API Endpoint

Para enviar un mensaje en WhatsApp, la solicitud de la API es hecho al endpoint:

http://api.gupshup.io/sm/api/v1/template/msg

Solicitud de la API

Solicitud de API de muestra

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}'

Solicitar encabezados

Cuerpo de solicitud

Respuesta de la API

Las solicitudes de la API de envío de mensajes recibidas por nuestra plataforma se procesan de forma asíncrona, por lo que siempre obtendrás una respuesta HTTP_SUCCESS(200 to 299) si la solicitud se realizó correctamente. La respuesta de la API incluye un objeto con un identificador de mensaje de Gupshup y un estado como enviado y tu Webhook recibirá message-event que indica que el mensaje enviado al cliente de la API de WhatsApp (que realmente envía el mensaje al cliente) está en cola o ha fallado.

{
«messageId»: «bf70b8c4-a5b9-4acd-b108-512ce704f4dc»,
«status»: «submitted»
}

El identificador de mensajes de Gupshup, es decir, messageId en la respuesta de la API, ayudará a rastrear los mensajes a través de los eventos, es decir, “enqueued”|“failed”|“sent”|“delivered”|“read” recibidos en el Webhook.

Ejemplo de solicitud de API para cada tipo de mensaje. Estos ejemplos son sólo para fines ilustrativos y no pueden ser utilizados. Debes crear tus propios ejemplos y hacer que se aprueben para poder hacer pruebas.

Enviar texto

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«Agent»,»Local Address»,»Tracking code»]}’

Multimedia
Enviar Imagen

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«Agent»,»Local Address»,»Tracking code»]}’ \
–data-urlencode ‘message={«type»:»image»,»image»:{«link»:»https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg»}}’

Enviar video

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«Agent»,»Local Address»,»Tracking code»]}’ \
–data-urlencode ‘message={«type»:»video»,»video»:{«link»: «https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4»}}’

Enviar documento/archivo

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«Agent»,»Local Address»,»Tracking code»]}’ \
–data-urlencode ‘message={«type»:»document»,»document»:{«link»:»https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf»,»filename»: «Sample funtional resume»}}’

Enviar ubicación

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«Agent»,»Local Address»,»Tracking code»]}’ \
–data-urlencode ‘message={«type»:»location»,»location»:{«longitude»:»»,»latitude»:»»}}’

Mensajes interactivos
Llamada a la acción

Para una plantilla interactiva de medios aprobada como esta:
Hi {{1}}, Please find the attached bill. For more details please visit our website. | [Visit Website,https://www.gupshup.io/developer/{{1}}]

Donde tenemos un marcador de posición en el cuerpo del mensaje, así como en el botón de llamada a la acción, la solicitud de la API puede ser:

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c49ee21d-4d39-452d-a6c1-25b7615e01e4″,»params»: [«John»,»docs/bot-platform/guide/whatsapp-api-documentation»]}’ \
–data-urlencode ‘message={«type»:»document»,»document»:{«link»:»https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf»,»filename»: «Sample funtional resume»}}’

Respuestas rápidas

Para una plantilla interactiva de medios aprobada como esta:
You can now view your Account Balance or Mini statement for
Account ending with {{1}} simply by selecting one of the options below. |
[View Account Balance] | [View Mini Statement]
Donde tenemos un marcador de posición en el cuerpo del mensaje y solo un botón de devolución de datos, la solicitud será:

curl –location –request POST ‘http://api.gupshup.io/sm/api/v1/template/msg’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–data-urlencode ‘source=917834811114’ \
–data-urlencode ‘destination=918x98xx21x4’ \
–data-urlencode ‘template={«id»: «c6aecef6-bcb0-4fb1-8100-28c094e3bc6b»,»params»: [«12323XXXX»]}’

Diversas APIs

API para obtener la lista de usuarios Opt-in

Esta API te ayudará a obtener una lista de todos los usuarios que han interactuado con el número telefónico de la empresa y su estado opt-in:
Curl request

Solicitud de la API

curl –location –request GET ‘https://api.gupshup.io/sm/api/v1/users/{{App_Name}}’ \
–header ‘apikey: {{La clave API de su cuenta}}’

Solicitud de la API

{
«status»: «success»,
«users»: [
{
«countryCode»: «91»,
«lastMessageTimeStamp»: 1585593959851,
«optinSource»: «URL»,
«optinStatus»: «OPT_IN»,
«optinTimeStamp»: 1585504095053,
«phoneCode»: «8x98xx21x4»
}
]
}

Marcar usuarios Opt-in

Las empresas están obligadas a obtener el opt-in antes de enviar notificaciones proactivas a los clientes. El opt-in se puede obtener de múltiples maneras, tanto dentro como fuera de WhatsApp. Esta API es realmente útil para obtener el Opt-in del usuario desde tu página web, flujos de respuesta de voz interactiva (IVR) o en un hilo de conversación de WhatsApp, etc.

Solicitud de la API

curl –location –request POST ‘https://api.gupshup.io/sm/api/v1/app/opt/in/{{App_Name}}’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘apikey: {{Gupshup_Account_APIKey}}’ \
–data-urlencode ‘user={{User_Mobile_Number}}’

Código de Respuesta de la API

202

Marcar usuaros Opt-out

Si un cliente desea cancelar la suscripción o dejar de recibir notifiaciones. La empresa puede utilizar esta API para hacer lo mismo.

Solicitud de la API

curl –location –request POST ‘https://api.gupshup.io/sm/api/v1/app/opt/out/{{App_Name}}’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘apikey: {{Gupshup_Account_APIKey}}’ \
–data-urlencode ‘user={{User_Mobile_Number}}’

El valor de Usuario_Móvil_Número es un número telefónico válido con código de país. Ejemplo: 918x98xx21x4

Código de Respuesta de la API

Obtener la lista de plantillas

Esta API se puede utilizar para varios propósitos, por ejemplo, si se ha enviado una plantilla para la revisión de WhatsApp, se puede programar el seguimiento del estado de la plantilla. También se puede utilizar para obtener el id de la plantilla generado por la plataforma para cada una de las enviadas a revisión de WhatsApp – el id de la plantilla es necesario para utilizar la API de mensajería de plantilla.

Entendamos esta API:

API Endpoint

https://api.gupshup.io/sm/api/v1/template/list/:AppName

Solicitar encabezados

Solicitud de la API

curl –location –request GET ‘https://api.gupshup.io/sm/api/v1/template/list/:AppName’ \
–header ‘apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a’

Respuesta de la API
HTTP response code: 200

{
«status»: «success»,
«templates»: [
{
«category»: «ACCOUNT_UPDATE»,
«createdOn»: 1580978917761,
«data»: «{{1}} debited with {{2}} on {{3}} for {{4}}.»,
«elementName»: «common_transaction_2»,
«id»: «05c82e91-05e5-4d35-b280-2d3d20feda38»,
«languageCode»: «en_US»,
«languagePolicy»: «deterministic»,
«master»: false,
«meta»: «{\»example\»:\»[Your Bank ac ending with 1245] debited with [Rs. 10000] on [11-Jan-2011] for [ATM cash withdrawal].\»}»,
«modifiedOn»: 1581966008618,
«status»: «APPROVED»,
«templateType»: «TEXT»,
«vertical»: «TRANSACTIONS»
},
{
«category»: «ISSUE_RESOLUTION»,
«createdOn»: 1593540550247,
«data»: «Hola! Soy {{1}} de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?»,
«elementName»: «recibimos_llamada»,
«id»: «072867eb-dd12-46f5-950d-2dd03a7677e5»,
«languageCode»: «es_MX»,
«languagePolicy»: «deterministic»,
«master»: true,
«meta»: «{\»example\»:\»Hola! Soy [Leon] de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?\»}»,
«modifiedOn»: 1593627001825,
«status»: «APPROVED»,
«templateType»: «TEXT»,
«vertical»: «ISSUE RESOLUTION»
}
]
}

La propiedad id es el ID de la plantilla.

Consultar el saldo de la billetera

Solicitud de la API

curl –location –request GET ‘https://api.gupshup.io/sm/api/v2/wallet/balance’ \
–header ‘apikey: {{Gupshup Account apikey}}’

Código de Respuesta de la API

200

Cuerpo de respuesta de API

{
«balance»: 1313.7675,
«status»: «success»
}