Nachricht senden

Entwickler können über die API Nachrichten an eine angegebene Konversations-ID senden.

Anfragemethode

POST

Anfrage-URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages

Authentifizierung

Einzelheiten zur Authentifizierung finden Sie in der API-Übersicht.

Textanfrage

Anfragebeispiel

curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ -d '{ "content": "Agent sendet eine Nachricht. Ist das normal?", "private": false, "content_attributes": { "in_reply_to": 29 } }'

              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "content": "Agent sendet eine Nachricht. Ist das normal?",  
    "private": false,
    "content_attributes": {
        "in_reply_to": 29   
    }
}'

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrage-Header

Feld	Typ	Beschreibung
Authorization	string	Verwenden Sie `Authorization: Basic base64(API Key:API Secret)` zur Authentifizierung. Bitte besuchen Sie die API-Key-Seite, um API Key und API Secret zu erhalten, verbinden Sie beide mit einem Doppelpunkt und kodieren Sie sie anschließend mit Base64.
Content-Type	application/json	Datentyp. Verwenden Sie `application/json` für reine Textnachrichten.

Pfadparameter

Feld	Typ	Erforderlich	Beschreibung
conversation_id	string	Ja	Konversations-ID.

Request-Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
content	String	Ja	Nachrichteninhalt.
private	Boolean	Nein	Gibt an, ob es sich um eine private Nachricht handelt. Standardwert ist `false`.
content_attributes	Object	Nein	Inhaltsattribute. Beim Antworten auf eine Nachricht kann beispielsweise die Nachrichten-ID über das Feld `in_reply_to` angegeben werden.

Text-Antwortbeispiel

Antwortbeispiel

{ "id": 3030, "content": "Agent sendet eine Nachricht. Ist das normal?", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331029, "private": false, "source_id": null, "sorting_id": 4, "sender": { "id": 3, "name": "TEST", "available_name": "TEST", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" } }

              
              {
    "id": 3030,
    "content": "Agent sendet eine Nachricht. Ist das normal?",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331029,
    "private": false,
    "source_id": null,
    "sorting_id": 4,
    "sender": {
        "id": 3,
        "name": "TEST",
        "available_name": "TEST",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Feld	Typ	Beschreibung
id	Int	Nachrichten-ID.
content	String	Nachrichteninhalt.
inbox_id	Int	Posteingangs-ID.
conversation_id	Int	Konversations-ID.
message_type	Int	Nachrichtentyp.
content_type	String	Inhaltstyp.
status	String	Nachrichtenstatus, z. B. "sent", "delivered" usw.
content_attributes	Object	Inhaltsattribute.
created_at	Int	Zeitstempel der Nachrichtenerstellung.
private	Boolean	Gibt an, ob es sich um eine private Nachricht handelt.
source_id	Int	Quell-ID.
sorting_id	Int	Sortier-ID.
sender	Object	Absenderinformationen.
id	Int	Absender-ID.
name	String	Absendername.
available_name	String	Anzeigename des Absenders.
avatar_url	String	Avatar-URL des Absenders.
type	String	Absendertyp (z. B. user).
availability_status	String	Online-Status des Absenders (z. B. offline).
thumbnail	String	Miniaturansicht des Absenders.

Bild-/Audio-/Dateianfrage

Anfragebeispiel

curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \ -H "Authorization: Basic base64(api_key:api_secret)" \ -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \ -F "content=Detailliertes Bild wie folgt"

              
              curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \
  -H "Authorization: Basic base64(api_key:api_secret)" \
  -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \
  -F "content=Detailliertes Bild wie folgt"

Diesen Codeblock im schwebenden Fenster anzeigen

Pfadparameter

Feld	Typ	Erforderlich	Beschreibung
conversation_id	string	Ja	Konversations-ID.

Bild-/Audio-/Datei-Antwortbeispiel

Antwortbeispiel

{ "id": 3031, "content": "Detailliertes Bild wie folgt", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331762, "private": false, "source_id": null, "sorting_id": 5, "sender": { "id": 3, "name": "Wenjie Yu", "available_name": "Wenjie Yu", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" }, "attachments": [ { "id": 199, "message_id": 3031, "file_type": "image", "account_id": 14, "extension": null, "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png", "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png", "file_size": 589136, "width": null, "height": null } ] }

              
              {
    "id": 3031,
    "content": "Detailliertes Bild wie folgt",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331762,
    "private": false,
    "source_id": null,
    "sorting_id": 5,
    "sender": {
        "id": 3,
        "name": "Wenjie Yu",
        "available_name": "Wenjie Yu",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    },
    "attachments": [
        {
            "id": 199,
            "message_id": 3031,
            "file_type": "image",
            "account_id": 14,
            "extension": null,
            "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png",
            "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png",
            "file_size": 589136,
            "width": null,
            "height": null
        }
    ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Feld	Typ	Beschreibung
id	Int	Nachrichten-ID.
content	String	Nachrichteninhalt.
inbox_id	Int	Posteingangs-ID.
conversation_id	Int	Konversations-ID.
message_type	Int	Nachrichtentyp.
content_type	String	Inhaltstyp.
status	String	Nachrichtenstatus, z. B. "sent", "delivered" usw.
content_attributes	Object	Inhaltsattribute.
created_at	Int	Zeitstempel der Nachrichtenerstellung.
private	Boolean	Gibt an, ob es sich um eine private Nachricht handelt.
source_id	Int	Quell-ID.
sorting_id	Int	Sortier-ID.
sender	Object	Absenderinformationen.
id	Int	Absender-ID.
name	String	Absendername.
available_name	String	Anzeigename des Absenders.
avatar_url	String	Avatar-URL des Absenders.
type	String	Absendertyp (z. B. user).
availability_status	String	Online-Status des Absenders (z. B. offline).
thumbnail	String	Miniaturansicht des Absenders.
attachments	Array	Liste der Anhangsinformationen.
id	Int	Anhang-ID.
message_id	Int	ID der zugehörigen Nachricht.
file_type	String	Dateityp (z. B. image).
account_id	Int	Konto-ID.
extension	String	Dateierweiterung.
data_url	String	Datei-URL.
thumb_url	String	Miniaturbild-URL (nur Bildtyp).
file_size	Int	Dateigröße (Byte).
width	Int	Dateibreite (nur Bildtyp).
height	Int	Dateihöhe (nur Bildtyp).

WhatsApp-Vorlagennachricht Anfragebeispiel

Anfragebeispiel

curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'\ -d '{ "content": "Anzeigetext für die Chat-Oberfläche", "message_type": "outgoing", "template_params": { "name": "order_update", "namespace": "optional_namespace", "language": "en_US", "category": "MARKETING", "processed_params": { "1": "John", "2": "versendet" }, "header_params": { "type": "text", "text_variables": { "1": "Bestellung #456" } }, "footer_params": { "text_variables": { "1": "Acme GmbH" } }, "button_params": [ { "index": 0, "sub_type": "url", "text": "track/12345" } ] } }'

              
              curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'\
-d '{
    "content": "Anzeigetext für die Chat-Oberfläche",
    "message_type": "outgoing",
    "template_params": {
      "name": "order_update",
      "namespace": "optional_namespace",
      "language": "en_US",
      "category": "MARKETING",
      "processed_params": {
        "1": "John",
        "2": "versendet"
      },
      "header_params": {
        "type": "text",
        "text_variables": {
         "1": "Bestellung #456" }
      },
      "footer_params": {
        "text_variables": { "1": "Acme GmbH" }
      },
      "button_params": [
        {
          "index": 0,
          "sub_type": "url",
          "text": "track/12345"
        }
      ]
    }
  }'

Diesen Codeblock im schwebenden Fenster anzeigen

Pfadparameter

Feld	Typ	Erforderlich	Beschreibung
conversation_id	string	Ja	Konversations-ID.

Request-Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
content	String	Ja	Nachrichteninhalt, der in der Chat-Oberfläche angezeigt wird.
message_type	String	Ja	Nachrichtentyp. Beim Senden einer Vorlagennachricht fest auf `outgoing` gesetzt.
template_params	Object	Ja	Parameterobjekt der Vorlagennachricht.
name	String	Ja	Vorlagenname.
namespace	String	Nein	Vorlagen-Namespace (verwendet von WhatsApp Cloud / 360Dialog).
language	String	Ja	Sprachcode der Vorlage, z. B. `en_US`.
category	String	Nein	Vorlagenkategorie, z. B. `MARKETING`.
processed_params	Object	Nein	Variablenwerte des Vorlagentextes. Der Schlüssel ist die Variablenposition (`"1"`, `"2"`) oder der Variablenname.
header_params	Object	Nein	Parameter der Vorlagen-Header-Komponente. Siehe Details unten.
footer_params	Object	Nein	Parameter der Vorlagen-Footer-Komponente. Siehe Details unten.
button_params	Array	Nein	Parameter der Vorlagen-Button-Komponente. Siehe Details unten.

Beschreibung der header_params-Parameter

Die Struktur von header_params variiert je nach Header-Typ:

Texttyp:

{ "type": "text", "text_variables": { "1": "Bestellung #456" } }

              
              {
  "type": "text",
  "text_variables": { "1": "Bestellung #456" }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Bildtyp:

{ "type": "image", "media_url": "https://example.com/image.jpg" }

              
              {
  "type": "image",
  "media_url": "https://example.com/image.jpg"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Videotyp:

{ "type": "video", "media_url": "https://example.com/video.mp4" }

              
              {
  "type": "video",
  "media_url": "https://example.com/video.mp4"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Dokumenttyp:

{ "type": "document", "media_url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }

              
              {
  "type": "document",
  "media_url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Standorttyp:

{ "type": "location", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Acme-Zentrale", "address": "Main St 123, San Francisco" } }

              
              {
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "Acme-Zentrale",
    "address": "Main St 123, San Francisco"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Feld	Typ	Erforderlich	Beschreibung
type	String	Ja	Header-Typ. Unterstützt `text`, `image`, `video`, `document`, `location`.
text_variables	Object	Nein	Wird beim Texttyp verwendet. Der Schlüssel ist die Variablenposition, der Wert ist der Ersatzinhalt.
media_url	String	Nein	Wird bei Medientypen verwendet. URL der Mediendatei.
filename	String	Nein	Wird beim Dokumenttyp verwendet. Dateiname.
location	Object	Nein	Wird beim Standorttyp verwendet.
latitude	Float	Ja	Breitengrad.
longitude	Float	Ja	Längengrad.
name	String	Nein	Name des Standorts.
address	String	Nein	Adresse des Standorts.

Beschreibung der footer_params-Parameter

{ "text_variables": { "1": "Acme GmbH" } }

              
              {
  "text_variables": { "1": "Acme GmbH" }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Feld	Typ	Erforderlich	Beschreibung
text_variables	Object	Nein	Der Schlüssel ist die Variablenposition, der Wert ist der Ersatzinhalt.

Beschreibung der button_params-Parameter

[ { "index": 0, "sub_type": "url", "text": "track/12345" }, { "index": 1, "sub_type": "quick_reply", "payload": "OPT_OUT" } ]

              
              [
  {
    "index": 0,
    "sub_type": "url",
    "text": "track/12345"
  },
  {
    "index": 1,
    "sub_type": "quick_reply",
    "payload": "OPT_OUT"
  }
]

Diesen Codeblock im schwebenden Fenster anzeigen

Feld	Typ	Erforderlich	Beschreibung
index	Int	Ja	Button-Index, beginnend bei 0.
sub_type	String	Ja	Button-Typ. Unterstützt `url`, `quick_reply`.
text	String	Nein	Wird bei Buttons vom Typ URL verwendet. URL-Suffix oder Weiterleitungspfad.
payload	String	Nein	Wird bei Buttons vom Typ quick_reply verwendet. Inhalt des zurückgegebenen Payloads.

Antwortbeispiel

Erfolgreiche Antwort

{ "id": 123, "content": "Anzeigetext für die Chat-Oberfläche", "message_type": 1, "status": "sent", "additional_attributes": { "template_params": { "name": "order_update", "language": "en_US", "category": "MARKETING" } } }

              
              {
  "id": 123,
  "content": "Anzeigetext für die Chat-Oberfläche",
  "message_type": 1,
  "status": "sent",
  "additional_attributes": {
    "template_params": {
      "name": "order_update",
      "language": "en_US",
      "category": "MARKETING"
    }
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlgeschlagene Antwort

{ "id": 123, "status": "failed", "content_attributes": { "external_error": "131047: Re-engagement message is not allowed" } }

              
              {
  "id": 123,
  "status": "failed",
  "content_attributes": {
    "external_error": "131047: Re-engagement message is not allowed"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Feld	Typ	Beschreibung
id	Int	Nachrichten-ID.
content	String	Nachrichteninhalt.
message_type	Int	Nachrichtentyp.
status	String	Nachrichtenstatus, z. B. `sent`, `delivered`, `failed` usw.
additional_attributes	Object	Zusätzliche Attribute.
template_params	Object	Informationen zu den gesendeten Vorlagenparametern.
content_attributes	Object	Inhaltsattribute. Enthält Fehlerinformationen, wenn der Versand fehlschlägt.
external_error	String	Externe Fehlerinformationen, die beim Fehlschlagen des Nachrichtenversands zurückgegeben werden.

Fehlgeschlagene Nachricht erneut senden

Wenn der Nachrichtenstatus failed ist, können Sie den Nachrichtenstatus zurücksetzen und die Nachricht über die folgende API erneut senden:

Anfrage-URL

POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages/:message_id/retry

Pfadparameter

Feld	Typ	Erforderlich	Beschreibung
conversation_id	string	Ja	Konversations-ID.
message_id	string	Ja	Nachrichten-ID.