Mensajes

/v1/messages

Usa el nodo messages para enviar mensajes de texto, objetos multimedia/documento y plantillas de mensaje a tus clientes.

Consulta las siguientes guías para obtener información acerca de los tipos específicos de mensajes que puedes enviar: mensajes de texto, mensajes multimedia, plantillas de mensajes y otros tipos de mensajes.

Antes de empezar

Necesitas lo siguiente:

Antes de enviar un mensaje, deberías enviar también una llamada a la API al nodo de contactos. La información de verificación de contactos se almacena en caché en el contenedor y, si esto no se hace, se podría generar un error de "Unkown Contact".

Restricciones

  • Se admiten los siguientes tipos de mensajes: texto, plantilla de mensaje, imágenes, documentos y audio.
  • Un mensaje de texto puede tener, como máximo, 4.096 caracteres.

Creación

Se envían mensajes haciendo una llamada /messages al nodo POST, independientemente del tipo de mensaje, aunque el contenido del cuerpo del mensaje JSON sí difiera para cada tipo de mensaje (texto, imagen, etc.).

Parámetros

Los siguientes parámetros son los más usados en solicitudes de la API /messages POST:

Nombre Descripción

type

Obligatorio para las plantillas de mensaje.

El tipo de mensaje que se envía.
Opciones:

  • text: valor predeterminado
  • image
  • audio
  • document
  • template: se usa para enviar un mensaje de plantilla con contenido multimedia
  • hsm

to

Obligatorio.

El identificador de WhatsApp a quien se envía el mensaje.

ttl
Quedará obsoleto en la v2.35

Opcional.

A partir de la v2.21.3: Duración del tiempo de vida (TTL).
Valor predeterminado: 7 días
Otras opciones: Las duraciones mínima y máxima compatibles oscilan entre 1 y 30 días (ambos valores incluidos).


Acepta una cadena con el formato de duración ISO-8601 o simplemente en segundos. Las duraciones deben especificarse con un múltiplo exacto de días. Cualquier otro valor intermedio se redondeará automáticamente al día más próximo. Consulta la sesión del objeto ttl para obtener más información.

recipient_type

Opcional.

Valor:individual

template

Obligatorio para los mensajes template.

Contiene toda la información de la plantilla.

hsm

Obligatorio para las plantillas de mensaje.

El elemento de contención del contenido del mensaje. Indica que el mensaje está altamente estructurado. Los parámetros que contiene proporcionan la estructura.

Objeto text

NombreDescripción

body

Obligatorio.

Contiene el texto del mensaje, que puede incluir formato y URL.

El objeto media

NombreDescripción

id

Se requiere cuando type es audio, document, image, sticker o video y no usas un enlace.

El identificador del objeto multimedia: se devuelve cuando el contenido multimedia se sube correctamente al cliente de la API de WhatsApp Business con el punto de conexión media.


No utilices este campo cuando el type del mensaje está establecido en text.

link

Se requiere cuando type es audio, document, image, sticker o video y no usas un identificador de contenido multimedia que fue subido.

Protocolo y URL del contenido multimedia que se enviará. Se usa solamente con URL HTTP y HTTPS.


No utilices este campo cuando el type del mensaje está establecido en text.

caption

Opcional.

Describe el contenido multimedia document, image o video específico.


No debe usarse con el contenido multimedia audio ni sticker.

filename

Opcional.

Describe el nombre de archivo del documento especificado. Se usa solamente con contenido multimedia document.

provider

Opcional.

Esta ruta se usa opcionalmente con link cuando no es posible acceder directamente al enlace HTTP o HTTPS y hacen falta configuraciones adicionales, como un token del portador. Para obtener más información sobre cómo configurar proveedores, consulta la documentación sobre proveedores de contenido multimedia.

Objeto contacts

Dentro de contacts, puedes anidar los siguientes objetos: addresses, emails, name, org, phone y urls.

NombreDescripción

addresses

Opcional.

Direcciones completas del contacto: consulta el objeto addresses.

birthday

Opcional.

Cadena con formato YYYY-MM-DD.

emails

Opcional.

Direcciones de correo electrónico del contacto: consulta el objeto emails.

name

Obligatorio.

Nombre completo del contacto: consulta el objeto name.

org

Opcional.

Información de la organización del contacto: consulta el objeto org.

phones

Opcional.

Número de teléfono de contacto: consulta el objeto phone.

urls

Opcional.

URL del contacto: consulta el objeto urls.

El objeto addresses

NombreDescripción

street

Opcional.

Nombre de la calle y número

city

Opcional.

Nombre de la ciudad.

state

Opcional.

Abreviatura del estado o la provincia.

zip

Opcional.

Código postal.

country

Opcional.

Nombre completo del país.

country_code

Opcional.

Abreviatura del país (dos letras).

type

Opcional.

Valores estándar:HOME, WORK.

El objeto emails

NombreDescripción

email

Opcional.

Dirección de correo electrónico

type

Opcional.

Valores estándar:HOME, WORK.

El objeto name

NombreDescripción

formatted_name

Obligatorio.

Nombre completo, tal como aparece habitualmente.

first_name

Opcional*.

Nombre.

last_name

Opcional*.

Apellido.

middle_name

Opcional*.

Segundo nombre.

suffix

Opcional*.

Sufijo del nombre.

prefix

Opcional*.

Prefijo del nombre.

* Es necesario incluir al menos uno de los parámetros opcionales junto con el parámetro formatted_name.

El objeto org

NombreDescripción

company

Opcional.

Nombre de la empresa del contacto.

department

Opcional.

Nombre del departamento del contacto.

title

Opcional.

Título del negocio del contacto.

El objeto phone

NombreDescripción

phone

Opcional.

Se completa automáticamente con el valor wa_id como número de teléfono con formato.

type

Opcional.

Valores estándar:CELL, MAIN, IPHONE, HOME, WORK.

wa_id

Opcional.

Identificador de WhatsApp.

El objeto urls

NombreDescripción

url

Opcional.

URL.

type

Opcional.

Valores estándar:HOME, WORK.

Objeto location

NombreDescripción

longitude

Obligatorio.

Longitud de la ubicación.

latitude

Obligatorio.

Latitud de la ubicación.

name

Opcional.

Nombre de la ubicación.

address

Opcional.

Dirección de la ubicación. Solo se muestra si name está presente.

Objeto template

Dentro de template, puedes anidar los objetos components y language.

NombreDescripción

namespace

Obligatorio.

Espacio de nombres de la plantilla.


A partir de la versión v2.27.8, este debe ser el espacio de nombres asociado a la cuenta de WhatsApp Business que posee el número de teléfono correspondiente al cliente de la API de WhatsApp Business actual, o el mensaje no se enviará.

name

Obligatorio.

Nombre de la plantilla.

language

Obligatorio.

Especifica el lenguaje en que se puede representar la plantilla. Solo funciona la política de lenguaje deterministic con los mensajes de plantilla multimedia. Consulta la sección Idioma para obtener más información.

components

Opcional.

Matriz que incluye los parámetros del mensaje.

Objeto components

Dentro de components, puedes anidar el objeto parameters. A su vez, puedes fijar type en button.

NombreDescripción

type

Obligatorio.

Describe el tipo component
Valores:header, body, footer

parameters

Opcional.

Matriz que incluye el contenido del mensaje.

Objeto parameters

NombreDescripción

type

Obligatorio.

Describe el tipo parameter.
Valores:text, currency, date_time, image, document, video


Los tipos de contenido multimedia (image, document y video) siguen el mismo formato que los que se usan en mensajes multimedia estándar; consulta la documentación sobre contenido multimedia para obtener más información. Actualmente, las plantillas de mensajes multimedia solo admiten documentos PDF.


Para obtener más información sobre currency y date_time, consulta la sección sobre parámetros localizables. Los parámetros currency y date_time para mensajes de template usan fallback_value en lugar de default. Consulta el ejemplo anterior de solicitud para ver un modelo.

El tipo de button

Dentro del objeto components, puedes fijar type en button. Estos son los parámetros de botón:

NombreDescripción

sub_type

Obligatorio.

Tipo de botón que se crea.
Valores: quick_reply y url.

index

Obligatorio.

Índice de posición del botón. Es posible tener hasta tres botones con valores 0-2 para los indicadores.

parameters

Obligatorio.

Parámetros del botón, que se definen en el momento de la creación en el administrador comercial. Incluye los siguientes parámetros:

  • type (Obligatorio): indica el tipo de parámetro del botón. Los valores compatibles son payload y text.
  • payload (Obligatorio para botones quick_reply): carga definida por el desarrollador que se devolverá cuando se haga clic en el botón junto con el texto de visualización del botón.
  • text (Obligatorio para botones url): sufijo proporcionado por el desarrollador que se agregará a un botón de URL dinámica creado previamente.

Objeto language

El parámetro language define la política de lenguaje para una plantilla de mensaje. Este campo se puede anidar dentro de los objetos hsm y template.

Nombre Descripción

policy

Obligatorio.

Predeterminada:deterministic
política de lenguaje que debe seguir el mensaje. La opción fallback quedará obsoleta con la v2.27.8. Obtén más información sobre las opciones de la política de idioma.

code

Obligatorio.

El código de idioma o configuración regional que se usará. Admite los formatos language y language_locale (por ejemplo, en y en_US).

Objeto hsm

La retirada del objeto hsm está planeada para una versión futura.

Nombre Descripción

namespace

Obligatorio.

Espacio de nombres que se utilizará. A partir de la v2.2.7, si el espacio de nombres no coincide con element_name, no se podrá enviar el mensaje.

element_name

Obligatorio.

Nombre del elemento que indica la plantilla que se utilizará en el espacio de nombres. A partir de la v2.2.7, si el espacio de nombres no coincide con element_name, no se podrá enviar el mensaje.

language

Obligatorio.

Permite la especificación de un lenguaje "deterministic" o "fallback". Consulta la sección Lenguaje para obtener más información.


Campo utilizado que ofrece una opción fallback, pero quedó obsoleto con v2.27.8.

localizable_params

Obligatorio.

Este campo es una matriz de valores que se aplicarán a las variables en la plantilla. Consulta la sección Parámetros localizables para obtener más información.

El objeto interactive

El objeto interactive suele tener 4 componentes principales: header, body, footer y action. Además, algunos de estos componentes pueden contener uno o más objetos diferentes:

  • Dentro de header, puedes anidar objetos media.
  • Dentro de action, puedes anidar objetos section y button.
NombreDescripción

type

Obligatorio.

Valores admitidos:

  • list: se utiliza para los mensajes de lista.
  • button: se utiliza para los botones de respuesta.

header

Opcional.

Contenido de encabezado que se muestra en la parte de arriba del mensaje. Consulta el objeto header para obtener más información.

body

Obligatorio.

El cuerpo del mensaje. Se permite un máximo de 1.024 caracteres. Se admiten emojis y Markdown.

footer

Opcional.

El pie de página del mensaje. Se permite un máximo de 60 caracteres. Se admiten emojis y Markdown.

action

Obligatorio.

La acción que deseas que realice el usuario después de leer el mensaje.

El objeto header

NombreDescripción

type

Obligatorio.

El tipo de encabezado que deseas que se utilice. Los valores admitidos son:

  • text: se usa para los mensajes de lista y los botones de respuesta.
  • video: se utiliza para los botones de respuesta.
  • image: se utiliza para los botones de respuesta.
  • document: se utiliza para los botones de respuesta.

text

Se requiere cuando type está configurado en text.

Texto del encabezado. No se deben superar los 60 caracteres. El formato admite emojis, pero no Markdown.

video

Se requiere cuando type está configurado en video.

Contiene el objeto media para este video.

image

Se requiere cuando type está configurado en image.

Contiene el objeto media para esta imagen.

document

Se requiere si type Está configurado en document.

Contiene el objeto media para este documento.

El objeto body

NombreDescripción

text

Obligatorio.

El contenido del cuerpo del mensaje. Máximo de 1024 caracteres. Se admiten emojis y Markdown. Se admiten enlaces.

NombreDescripción

text

Se requiere cuando el objeto footer está presente.

El contenido del pie de página. No se deben superar los 60 caracteres. Se admiten emojis y Markdown. Se admiten enlaces.

El objeto action

NombreDescripción

button

Se requiere para los mensajes de lista.

Contenido del botón. No puede ser una cadena vacía y debe ser único dentro del mensaje. Máximo de 20 caracteres. No admite ni emojis ni Markdown.

buttons

Se requiere para los mensajes con botón de respuesta.

Un botón puede contener los siguientes parámetros:

  • type: el único type admitido es reply (para mensajes con botón de respuesta)
  • title: título del botón. No puede ser una cadena vacía y debe ser único dentro del mensaje. Máximo de 20 caracteres. No admite ni emojis ni Markdown.
  • id: identificador único para el botón. Máximo de 256 caracteres. Se devuelve este identificador en el webhook cuando el usuario hace clic en el botón.

sections

Se requiere para los mensajes de lista.

Matriz de objetos section. Hay un mínimo de 1 y un máximo de 10. Consulta el objeto section.

El objeto section

NombreDescripción

title

Se requiere si el mensaje tiene más de una section.

Título de la sección.

rows

Se requiere para los mensajes de lista.

Contiene una lista de filas.

Cada una de estas fila debe contener un title y un ID. Puedes agregar un description, aunque es opcional.


Ejemplo:

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

Ejemplos

Mensajes de audio:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

Mensajes de documentos con filename:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "caption": "your-document-caption-to-be-sent",
      "filename": "your-document-filename"
  }
}

Mensajes de documentos con link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-document-caption"
    }
}

Mensajes de video con link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",
  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-video-caption"
    }
  }
}

Mensajes de texto:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

Mensajes interactivos (listas):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

Mensajes interactivos (botones de respuesta):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

La respuesta a la llamada incluye una combinación de los siguientes componentes: meta, messages (carga) y errors. Consulta Respuestas de la API de WhatsApp Business para obtener más información.

El siguiente es un ejemplo de payload en una respuesta: los objetos "meta" y "error" se omiten por motivos de brevedad.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

Si la solicitud se realiza correctamente, recibirás una respuesta con un identificador de mensaje. Si la solicitud devuelve una sección errors, verifica el mensaje que la originó y corrige los errores antes de volver a enviarla. Consulta Códigos de error del cliente de la API de WhatsApp Business y Códigos de estado HTTP para obtener más información sobre errores.

Aplicar formato en mensajes de texto

WhatsApp permite aplicar formato en los mensajes. Para aplicar formato en todo o parte del mensaje, usa los siguientes símbolos de formato:

Aplicar formatoSímboloEjemplo

Negrita

Asterisco (*)

Tu total es *10.50 USD*.

Cursiva

Guion bajo (_)

Bienvenido a _WhatsApp_.

Tachado

Tachado (~)

¡Esto es ~mejor~ perfecto!

Code

Tres acentos graves (```)

```print 'Hello World';```

Rendimiento

En este contexto, el rendimiento representa la cantidad de mensajes que se pueden enviar en un segundo cualquiera usando el cliente de la API de WhatsApp Business. El rendimiento máximo alcanzable depende de varios factores; el más importante tiene que ver con la configuración elegida del cliente y con el hecho de un mensaje se envíe o no a un usuario nuevo o existente; la configuración de sesiones de cifrado lleva un poco más de tiempo al enviar mensajes a un usuario nuevo.

Configuración del clienteMensajes admitidos por segundo

Un fragmento

70

Múltiples fragmentos (32 fragmentos)

250

Preguntas frecuentes

No.

Si un usuario se comunica con una empresa, la empresa puede responder con cualquier tipo de mensaje en las siguientes 24 horas. Este tipo de mensaje es gratuito.

Pero si la empresa se comunica con un usuario antes de que el usuario envíe un mensaje o después del transcurso de 24 horas, la empresa solo puede enviar una plantilla de mensaje. Esta es una notificación pagada.

Los mensajes de texto sin formato y los mensajes de contenido multimedia no funcionarán fuera de esta ventana de 24 horas. Esto dará como resultado una devolución de llamada fallida con el error 470.

Nota: No envíes el mismo mensaje una y otra vez al mismo destinatario mediante la API de WhatsApp Business.

Puede que haya varios motivos por los que las velocidades de entrega no sean del 100%. Entre algunos casos frecuentes se incluye el de los usuarios que tienen acceso esporádico a la red o que están inactivos durante un período.

Los mensajes que pueden entregarse por WhatsApp tienen una velocidad de entrega muy alta. Sin embargo, es posible que haya muchos motivos por los cuales un mensaje puede no entregarse. Podrás acceder al estado exacto de un mensaje mediante la supervisión de tus devoluciones de llamadas. Esto es diferente al envío de mensajes por SMS, por ejemplo, en los que no tienes acceso al estado final de la entrega y volver a enviar el mensaje puede, de hecho, producir un resultado diferente.

Los mensajes pueden no entregarse debido a que el teléfono de un usuario está fuera de servicio o no tiene batería, o porque el usuario lo ha perdido y está por obtener uno nuevo y ha desactivado la SIM. Es posible que existan errores en la capacidad de los clientes de la empresa de conectarse a la red. Además, puede que las devoluciones de llamadas (Webhooks) no se estén entregando. Puedes supervisar estas situaciones a través del nodo de health. Puedes activar las devoluciones de llamadas de recepción del servidor para confirmar que el mensaje fue recibido en la nube del servidor de WhatsApp.

Siempre y cuando el usuario haya reestablecido la conexión a la red, se le entregarán todos los mensajes que le hayas enviado. Recibir más de un mensaje con el mismo contenido es una mala experiencia para los usuarios. Lo más probable es que eso los predisponga a bloquearte o a quejarse. Lo más probable es que pases a ser un remitente prohibido.

Si envías un mensaje y recibes un identificador de mensaje de la API, has hecho lo posible por enviar este mensaje. No vuelvas a enviar el mismo contenido al mismo destinatario.

Si observas bajas velocidades de entrega durante un período prolongado, abre un ticket de asistencia en Asistencia directa.

Cuando envías un mensaje, apenas recibes un identificador de mensaje, significa que el mensaje se almacenó en la base de datos. El cliente de la API de WhatsApp Business seguirá intentando enviar ese mensaje hasta que el servidor de WhatsApp confirme la recepción. Este proceso no tiene cronograma final. El servidor de WhatsApp intentará entonces entregar ese mensaje al teléfono del usuario. Si el teléfono del usuario no está en internet, el mensaje se almacenará durante 30 días antes de que el servidor de WhatsApp lo descarte.

Sí. WhatsApp te permite dar formato al texto seleccionado dentro de tus mensajes con negrita, cursiva, tachado o monoespacio.

Actualmente, no existe forma de ver cuántos o qué usuarios han bloqueado tu empresa. El mejor indicador sería detectar las devoluciones de llamada del estado y si no recibes el estado delivered, quiere decir que el usuario ha bloqueado tu empresa o que no tiene conexión a la red. Consulta la documentación sobre Webhook para obtener más detalles.

Si un usuario bloqueó tu empresa, la API de contactos seguirá devolviendo ese número de teléfono como usuario de WhatsApp válido. Sin embargo, cuando envíes el mensaje, no se entregará. Si es un mensaje pagado, no se te cobrará.

No, no se puede garantizar que el orden de llegada de los mensajes sea el mismo que el orden en el que los mensajes fueron enviados. Si en tu caso el orden es fundamental, te sugerimos esperar la devolución de llamada entregada del primer mensaje antes de enviar el segundo mensaje.

Al utilizar el nodo messages, debes configurar el encabezado Content-Type como application/json para que el cliente de la API de WhatsApp Business analice de manera apropiada el cuerpo del mensaje. Además existe un encabezado de Authorization que debe configurarse y que debe contener un token de acceso vigente. Consulta la documentación Inicio de sesión y autenticación para obtener información sobre cómo obtener tu token y saber cuándo caduca.

Puede haber casos en los que necesites más tiempo para tratar una consulta del cliente y que solo puedas dar una respuesta pasadas las 24 horas. Te recomendamos crear plantillas de mensaje para:

  • Entregar el resultado al usuario
  • Solicitar al usuario que responda para activar la ventana de atención al cliente

En ambos casos, asegúrate de ofrecer el mayor contexto posible en la plantilla de mensaje. Por ejemplo:

  • "Hola {{1}}, respecto al problema informado anteriormente, lamentamos notificarte que {{2}}. Te pedimos disculpas por las molestias ocasionadas".
  • "Se ha actualizado tu ticket de asistencia. Por favor responde si sigues necesitando asistencia".