Mensajes

/v1/messages

Usa el nodo messages para enviar texto, contenido multimedia, contactos, ubicaciones y mensajes interactivos, así como plantillas de mensajes, a tus clientes.

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

Antes de empezar

Necesitas lo siguiente:

• Autenticarte y recibir un identificador de autenticación que te permita acceder al servicio. Consulta la documentación de inicio de sesión y autenticación para obtener más información sobre cómo hacerlo.
• Verificar la cuenta de WhatsApp a la que quieres enviar mensajes y obtener el identificador de usuario de WhatsApp. Para obtener más información sobre cómo hacerlo, consulta la documentación sobre contactos.
• Reunir los requisitos de servicio del control de desconexión para los mensajes.

Restricciones

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

Creación

Para enviar mensajes, debes realizar una llamada POST al nodo /messages independientemente del tipo de mensaje. El contenido del cuerpo del mensaje JSON es distinto para cada tipo de mensaje (texto, imagen, etc.).

Parámetros

Estos son los parámetros principales que se utilizan en las solicitudes POST de /messages:

Objeto de texto

Objeto multimedia

Para la API local, se devuelve el identificador del objeto multimedia cuando el contenido multimedia se sube correctamente al cliente de la implementación de referencia/local de WhatsApp Business con el extremo media.

Objeto de contactos

En contacts, puedes anidar los objetos siguientes: addresses, emails, name, org, phone y urls. Los objetos en plural se deben incluir en una matriz, como se muestra en el siguiente ejemplo.

Ejemplo de un objeto contacts con objetos en plural anidados en él:

"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 de ubicación

Objeto de plantilla

En template, puedes anidar los objetos components y language.

Objeto de componentes

En components, puedes anidar el objeto parameters. Además, puedes establecer type en button.

Objeto de parámetros

Tipo de botón

En el objeto components, puedes establecer type en button. Estos son los parámetros del botón:

Ejemplo del tipo button con quick_reply como valor del parámetro sub_type:

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

Ejemplo del tipo button con copy_code como valor del parámetro sub_type:

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

Objeto hsm

Objeto interactivo

Objeto de acción

Ejemplos

Mensajes de audio:

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

Mensajes de documento, mediante filename:

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

Mensajes de documento, mediante link:

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

Mensajes de vídeo, mediante 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 sobre un solo producto y sobre varios):

{ 
  "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 sobre varios productos):

{ 
  "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 (flujos):

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

A continuación, se muestra un ejemplo del elemento payload en una respuesta. Los objetos de metadatos y de errores se omiten para mayor brevedad.

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

Si la solicitud se realiza correctamente, recibes una respuesta con un identificador de mensaje. Si la solicitud devuelve una sección errors, comprueba el mensaje de origen 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 implementación de referencia/local de WhatsApp Business y Códigos de estado HTTP.

Si la solicitud se retiene para evaluar su calidad, la respuesta incluirá una propiedad message_status con un mensaje en el que se indica que el mensaje no se ha enviado inmediatamente y que se enviará o anulará una vez validada la calidad. Esta propiedad solo aparecerá si el mensaje se retiene.

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

Aplicar formato en los mensajes de texto

WhatsApp permite aplicar algunas opciones de formato a los mensajes. Para formatear un mensaje, o parte de este, usa los símbolos de formato siguientes:

Rendimiento

En este contexto, el rendimiento representa el número de mensajes que se pueden enviar en cualquier momento dado mediante el cliente de la implementación de referencia/local de WhatsApp Business. El rendimiento máximo alcanzable depende de distintos factores. Los más importantes son la elección que haces de la configuración del cliente y si un mensaje se envía a un nuevo usuario o a uno existente. Las sesiones de cifrado tardan un poco más en configurarse cuando se envían mensajes a un nuevo usuario.

Preguntas frecuentes

Más información

• Documentación de inicio de sesión y autenticación
• Documentación de contactos
• Códigos de error del cliente de la implementación de referencia/local de WhatsApp Business
• Códigos de estado HTTP