Mensajes

/v1/messages

Usa el nodo messages para enviar texto, contenido multimedia, contactos, ubicaciones, mensajes interactivos y plantillas de mensajes 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, mensajes de ubicación y contactos, mensajes interactivos, plantillas de mensajes, plantillas de mensajes multimedia y plantillas de mensajes interactivos.

Antes de empezar

Necesitas lo siguiente:

• Autenticarte y recibir un token de autenticación que te permitirá acceder al servicio. Consulta la documentación sobre el inicio de sesión y la autenticación para obtener más información sobre el proceso.
• Verificar la cuenta de WhatsApp a la que quieres enviar mensajes y de la que quieres obtener el identificador de usuario de WhatsApp. Consulta la documentación sobre contactos para obtener más información acerca del proceso.
• Conocer los requisitos del servicio de control de corte de mensajes.

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 POST de /messages:

Objeto "Texto"

Objeto "Contenido multimedia"

En el caso de la API de instalaciones locales, se devuelve el identificador del objeto de contenido multimedia cuando el contenido multimedia se sube correctamente al cliente de instalaciones locales/referencia de WhatsApp Business mediante el media punto de conexión.

Objeto "Contactos"

Dentro de contacts, puedes anidar los siguientes objetos: addresses, emails, name, org, phone y urls. Los objetos pluralizados se deben anidar en una matriz, como en el siguiente ejemplo.

Ejemplo de un objeto contacts con objetos pluralizados anidados en su interior:

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

Objeto "Location"

Objeto "Template"

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

Objeto "Components"

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

Objeto "Parameter"

Tipo de botón

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

Ejemplo del tipo button con sub_type quick_reply:

 {
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": 
     [{
    	"type": "payload",
    	"payload": "Yes-Button-Payload"
     }]
 } 

Ejemplo del tipo button con sub_type copy_code

    
 { 
    "type": "button", 
    "sub_type": "copy_code", 
    "index": 0, 
    "parameters": 
    [{ 
     "type": "coupon_code", 
     "coupon_code": "DISCOUNT20" 
    }] 
 }

Objeto "Hsm"

Objeto "Interactive"

Objeto "Action"

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

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

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": "interactive",
  "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": "interactive",
  "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

}

Mensajes interactivos (mensajes de productos individuales y múltiples):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "
      
      _id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

Mensajes interactivos (mensajes de productos múltiples):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "catalog_id":"catalog-id",
        "sections": [
             {
             "title": "section-title",             
             "product_items": [
                  { "product_retailer_id": "product-SKU-in-catalog" },
                  { "product_retailer_id": "product-SKU-in-catalog" },
                            ...
              ]},
              {
              "title": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

Mensajes interactivos (mensajes de catálogo):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "catalog_message",
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "name": "catalog_message",
      	"parameters":{ 
      	  "thumbnail_product_retailer_id": "product-SKU-in-catalog"
      	}
     },  
    }
}

Mensajes interactivos (procesos):

{
  "recipient_type": "individual",
  "to": "{{Recipient-WA-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": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": { # optional
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}

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. Para obtener más información sobre los errores, consulta Códigos de error del cliente de la API de instalaciones locales/referencia de WhatsApp Business y Códigos de estado HTTP.

Si la solicitud está sujeta a una evaluación de calidad, la respuesta contendrá una propiedad message_status con un mensaje, en el que se indica que el mensaje no fue enviado inmediatamente. El mensaje se enviará u omitirá después de que se haya validado la calidad. Esta propiedad solo existirá si el mensaje se retiene.

    {
      "messages": [{ 
        "id": "message-id",
        "message_status": "Message has been held because quality assessment is pending",
      }]    
    }
    

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:

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 instalaciones locales/referencia 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 que 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.

Preguntas frecuentes

Más información

• Documentación sobre el inicio de sesión y la autenticación
• Documentación sobre contactos
• Códigos de error del cliente de la API de instalaciones locales/referencia de WhatsApp Business
• Códigos de estado HTTP