Messages

/v1/messages

Utilisez le nœud messages pour envoyer du texte, du contenu multimédia, des contacts, des lieux, des messages interactifs, ainsi que des modèles de message à votre clientèle.

Pour plus d’informations sur les types de messages spécifiques que vous pouvez envoyer, consultez les guides suivants : Textos, Messages multimédias, Messages de contact et de lieu, Messages interactifs, Modèles de message, Modèles de message multimédia, et Modèles de message interactif.

Avant de commencer

Réalisez les actions suivantes :

• Authentifiez-vous et recevez un token d’authentification vous permettant d’accéder au service. Pour savoir comment procéder, consultez la documentation sur la connexion et l’authentification.
• Vérifiez le compte WhatsApp auquel vous souhaitez envoyer des messages et obtenez son identifiant utilisateur·ice WhatsApp. Pour savoir comment procéder, consultez la documentation sur les contacts.
• Respectez les exigences de service en matière de contrôle de diffusion des messages.

Contraintes

• Le nœud prend en charge les types de messages suivants : texto, modèles de message, images, documents et audio.
• Un texto peut contenir jusqu’à 4 096 caractères.

Création

Pour envoyer un message, quel que soit le type, vous devez effectuer un appel POST au nœud /messages. Toutefois, le contenu du corps des messages JSON diffère pour chaque type de message (texte, image, etc.).

Paramètres

Les paramètres principaux suivants sont utilisés dans les requêtes POST /messages :

Objet de texte

Objet de contenu multimédia

Pour l’API On-Premises, l’ID d’objet multimédia est renvoyé lorsque le contenu multimédia est correctement importé dans le client WhatsApp Business sur site/référence avec le point de terminaison media.

Objet de contacts

Dans contacts, vous pouvez imbriquer les objets suivants : addresses, emails, name, org, phone et urls. Les objets au pluriel doivent être empaquetés dans un tableau comme illustré dans l’exemple ci-dessous.

Exemple d’un objet contacts avec des objets au pluriel imbriqués :

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

Objet de lieu

Objet de modèle

Dans template, vous pouvez imbriquer les objets components et language.

Objet de composants

Dans components, vous pouvez imbriquer l’objet parameters. Par ailleurs, vous pouvez définir type sur button.

Objet de paramètre

Type de bouton

Dans l’objet components, vous pouvez définir type sur button. Voici les paramètres du bouton :

Exemple du type button avec le sous-type quick_reply :

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

Exemple du type button avec le sous-type copy_code :

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

Objet Hsm

Objet interactif

Objet d’action

Exemples

Messages vocaux :

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

Messages incluant un document, en utilisant filename :

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

Messages incluant un document, en utilisant link :

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

Messages vidéo, en utilisant link :

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

Textos :

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

Messages interactifs (listes) :

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

}

Messages interactifs (boutons de réponse) :

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

}

Messages interactifs (messages concernant un seul ou plusieurs produits) :

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

Messages interactifs (messages concernant plusieurs produits) :

{ 
  "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" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

Messages interactifs (messages de catalogue) :

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

Messages interactifs (flux) :

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

Voici un exemple de payload dans une réponse. Les métadonnées et les objets d’erreur n’apparaissent pas dans un souci de concision.

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

Si la requête a bien été envoyée, vous recevrez une réponse avec un ID de message. Si la requête renvoie une section errors, vérifiez le message de départ et corrigez les erreurs avant de la renvoyer. Pour plus d’informations au sujet des erreurs, consultez les sections Codes d’erreur du client WhatsApp Business sur site/référence et Codes d’état HTTP.

Si la requête est retenue pour une évaluation de la qualité, la réponse contiendra une propriété message_status avec un message indiquant que le message n’a pas été envoyé immédiatement et qu’il sera envoyé ou abandonné après la validation de la qualité. Cette propriété n’existera que si le message est retenu.

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

Formatage dans les textos

WhatsApp permet un certain formatage dans les messages. Pour formater tout ou partie d’un message, utilisez ces symboles de formatage :

Performance

Dans ce contexte, la performance représente le nombre de messages pouvant être envoyés dans une seconde donnée à l’aide du client WhatsApp Business sur site/référence. La performance maximale réalisable dépend de plusieurs facteurs, le plus important étant le choix de la configuration de votre client et si le ou la destinataire du message est un·e nouvel·le utilisateur·ice ou un·e utilisateur·ice existant·e. La configuration des sessions de chiffrement prend un peu plus de temps lorsqu’un message est envoyé à un·e nouvel·le utilisateur·ice.

Questions/réponses

En savoir plus

• Documentation sur la connexion et l’authentification
• Documentation sur les contacts
• Codes d’erreur du client WhatsApp Business sur site/référence
• Codes d’état HTTP