Outbound messages
The process of sending and receiving outbound open messages includes the following tasks:
Sending outbound messages to an Open Messaging Conversation
An Open Messaging Conversation is initiated either by an inbound message or by sending an agentless outbound Open message (see below).
Send an agentless outbound text message
An agentless outbound Open Message can be sent to initiate an Open Messaging Conversation.
Send the request POST /api/v2/conversations/messages/agentless.
Set toAddressMessengerType to open.
{
"fromAddress": "<Integration ID>",
"toAddress": "messaging-user@externalservice.com",
"toAddressMessengerType": "open",
"textBody": "Outbound message text!"
}Send an outbound open message from an agent
Text message
To send a text-only message, send the request POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages.
{
"textBody": "Outbound message text!"
}Message with media
An agent can send an open message with attached media, such as an image.
Note In order to include attached media, an open message must originate from an agent.
Receive an outbound message on your webhook
Each outbound message that you send with POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages results in a POST webhook request to outboundNotificationWebhookUrl. As part of the request process, we automatically transform the message payload into the Outbound Open NormalizedMessage Format.
For validation purposes, the message signature is set to X-Hub-Signature-256. For more information, see Validate a notification from an outbound open message.
Examples of normalized messages
Text message
The following example shows how text-only messages are normalized. Note that the transformed message is the same, regardless of whether the message originated from an agent or as an agentless outbound message.
Each message must have a unique combination of Messaging Platform Message ID ("id") and timestamp ("time"), otherwise the message will not be sent.
{
"id": "<Messaging Platform Message ID>",
"channel": {
"platform": "Open",
"type": "Private",
"to": {
"id": "messaging-user@externalservice.com",
"idType": "email"
},
"from": {
"id": "<Integration ID>"
},
"time": "2021-01-21T16:47:07.592Z"
},
"type": "Text",
"text": "Outbound message text!",
"direction": "Outbound"
}Message with media
The following example shows how a message with attached media are normalized. Note that open messages with attached media must be sent by an agent.
{
"id": "<Messaging Platform Message ID>",
"channel": {
"platform": "Open",
"type": "Private",
"to": {
"id": "messaging-user@externalservice.com",
"idType": "email"
},
"from": {
"id": "<Integration ID>"
},
"time": "2021-01-21T16:47:07.592Z"
},
"type": "Text",
"content": [{
"contentType": "Attachment",
"attachment": {
"mediaType": "Image",
"url": "https://www.genesys.com/media/4a30f651-ba-genesys-logo-color.png",
"mime": "image/png",
"filename": "4a30f651-ba-genesys-logo-color.png"
}
}],
"direction": "Outbound"
}Messaging Template message
The following example shows how messaging template messages are normalized.
{
"id": "<Messaging Platform Message ID>",
"channel": {
"platform": "Open",
"type": "Private",
"to": {
"id": "messaging-user@externalservice.com",
"idType": "email"
},
"from": {
"id": "<Integration ID>"
},
"time": "2021-01-21T16:47:07.592Z"
},
"type": "Structured",
"direction": "Outbound",
"content": [{
"contentType": "Notification",
"template": {
"text": "Your order 12345 shipped on Friday.",
"parameters": [
{
"name": "order number",
"text": "12345"
},
{
"name": "shipping day",
"text": "Friday"
}
]
}
}]
}Outbound receipt for an inbound message
This example is an outbound receipt for an inbound message. For more information about receipts, see Message receipts.
{
"id": "<Original Messaging Platform Message ID>",
"channel": {
"platform": "Open",
"type": "Private",
"from": {
"id": "messaging-user@externalservice.com",
"idType": "email"
},
"to": {
"id": "<Integration ID>"
},
"time": "2021-01-21T16:47:08.592Z"
},
"type": "Receipt",
"status": "Published",
"direction": "Inbound"
"isFinalReceipt":true,
}Outbound typing event
The following example shows how typing event messages are normalized. When using Genesys Cloud Agent UI, these events will be sent automatically as long as the integration is configured for the outbound typing setting. If not using Agent UI, then typing events can be sent from the Conversation using POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/typing.
{
"id": "<Messaging Platform Message ID>",
"channel": {
"id": "<Integration ID>",
"platform": "Open",
"type": "Private",
"to": {
"id": "messaging-user@externalservice.com"
},
"from": {
"nickname": "<Integration Name>",
"id": "<Integration ID>",
"idType": "Opaque"
},
"time": "2023-09-25T13:41:24.276Z",
"messageId": "<Messaging Platform Message ID>"
},
"type": "Event",
"events": [
{
"eventType": "Typing",
"typing": {
"type": "On",
"duration": 5000
}
}
],
"direction": "Outbound"
}