Nachrichten

/v1/messages

Nutze den messages-Node, um Text, Medien, Kontakte, Standorte und interaktive Nachrichten und Nachrichtenvorlagen an deine Kund*innen zu senden.

In den folgenden Leitfäden findest du Informationen zu den spezifischen Arten von Nachrichten, die du versenden kannst: Textnachrichten, Mediennachrichten, Kontakt- und Standortnachrichten, Interaktive Nachrichten, Nachrichtenvorlagen, Vorlagen für Mediennachrichten und Vorlagen für interaktive Nachrichten.

Bevor du beginnst

Voraussetzungen:

• Nachdem du dich authentifiziert hast, erhältst du ein Authentifizierungstoken, mit dem du auf den Service zugreifen kannst. Weitere Informationen dazu findest du in der Dokumentation zu Anmeldung und Authentifizierung.
• Bestätige das WhatsApp-Konto, an das du eine Nachricht senden möchtest, und rufe dessen WhatsApp-Nutzer*innen-ID ab. Weitere Informationen dazu findest du in unserer Dokumentation zu Kontakten.
• Die Nachricht muss den Anforderungen für Cut-off-Dienste entsprechen.

Einschränkungen

• Die folgenden Nachrichtentypen werden unterstützt: Text, Nachrichtenvorlagen, Bilder, Dokumente und Audio.
• Eine Textnachricht kann max. 4.096 Zeichen lang sein.

Erstellen

Du sendest Nachrichten unabhängig vom Nachrichtentyp, indem du einen POST-Aufruf an den /messages-Node sendest. Der Inhalt des JSON-Nachrichtentexts ist bei jedem Nachrichtentyp anders (SMS, Bild usw.).

Parameter

Dies sind die Hauptparameter, die in /messages-POST-Anforderungen verwendet werden:

Objekt „text“

Objekt „media“

Die Medienobjekt-ID für die On-Premises-API wird zurückgegeben, wenn die Medien erfolgreich über den media-Endpunkt in den WhatsApp Business On-Premises-/Referenz-Client hochgeladen wurden.

Objekt „contacts“

Innerhalb von contacts kannst du folgende Objekte verschachteln: addresses, emails, name, org, phone und urls. Pluralisierte Objekte müssen wie unten dargestellt in einem Array eingeschlossen werden.

Beispiel eines contacts-Objekts mit eingeschlossenen pluralisierten Objekten:

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

Objekt „location“

Objekt „template“

Innerhalb von template kannst du die Objekte components und language verschachteln.

Objekt „components“

Innerhalb von components kannst du das Objekt parameters verschachteln. Zusätzlich kannst du als typebutton festlegen.

Parameterobjekt

Typ „button“

Innerhalb des components-Objekts kannst du für typebutton festlegen. Die Button-Parameter sehen wie folgt aus:

Beispiel eines button-Typs mit dem sub_type quick_reply:

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

Beispiel eines button-Typs mit dem sub_type copy_code

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

Objekt „hsm“

Objekt „interactive“

Objekt „action“

Beispiele

Audionachrichten:

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

Dokumentnachrichten mit filename:

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

Dokumentnachrichten mit link:

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

Videonachrichten mit link:

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

Textnachrichten:

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

Interaktive Nachrichten (Listen):

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

}

Interaktive Nachrichten (Antwort-Buttons):

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

}

Interaktive Nachrichten (Nachrichten für einzelne und mehrere Produkte):

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

Interaktive Nachrichten (Nachrichten für mehrere Produkte):

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

Interaktive Nachrichten (Katalognachrichten):

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

Interaktive Nachrichten (Flows):

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

Im Folgenden findest du ein Beispiel für payload in einer Antwort. Die Meta- und Fehlerobjekte wurden der Kürze halber weggelassen.

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

Bei erfolgreicher Anfrage erhältst du eine Antwort mit einer Nachrichten-ID. Wenn die Anfrage einen errors-Abschnitt zurückgibt, prüfe die Ursprungsnachricht und korrigiere die Fehler, bevor du die Anfrage erneut sendest. Weitere Informationen zu Fehlern findest du unter Fehlercodes des WhatsApp Business On-Premises-/Referenz-Clients und HTTP-Statuscodes.

Wenn die Anfrage aufgrund der Qualitätsbewertung zurückgehalten wird, enthält die Antwort die message_status-Eigenschaft mit einer Nachricht, die angibt, dass die Nachricht nicht direkt gesendet wurde und nach der Überprüfung der Qualität gesendet oder verworfen wird. Diese Eigenschaft ist nur vorhanden, wenn die Nachricht zurückgehalten wird.

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

Formatierung in Textnachrichten

WhatsApp unterstützt einige Formatierungen in Nachrichten. Mit diesen Symbolen kannst du eine komplette Nachricht oder bestimmte Nachrichteninhalte formatieren:

Performance

In diesem Zusammenhang steht Performance für die Anzahl der Nachrichten, die in einer Sekunde mit dem WhatsApp Business On-Premises-/Referenz-Client gesendet werden können. Die maximal erreichbare Performance hängt von verschiedenen Faktoren ab. Die wichtigsten Faktoren sind dein Client-Setup und die Frage, ob eine Nachricht an eine*n neue*n oder eine*n vorhandene*n Nutzer*in gesendet werden soll. Die Einrichtung von Verschlüsselungssitzungen dauert etwas länger, wenn Nachrichten an eine*n neue*n Nutzer*in gesendet werden.

FAQ

Mehr dazu

• Dokumentation zu Anmeldung und Authentifizierung
• Dokumentation zu Kontakten
• Fehlercodes des WhatsApp Business On-Premises-/Referenz-Clients
• HTTP-Statuscodes