WikiSysop: Created page with "{{Article |Standalone=No |DisplayName=Third-Party Messaging Overview |Context=The Third-Party Messaging API delivers messages between external messaging services (such as SMS..."

2023-11-26T04:31:28Z

Created page with "{{Article |Standalone=No |DisplayName=Third-Party Messaging Overview |Context=The Third-Party Messaging API delivers messages between external messaging services (such as SMS..."

New page

{{Article
|Standalone=No
|DisplayName=Third-Party Messaging Overview
|Context=The Third-Party Messaging API delivers messages between external messaging services (such as SMS or email) and Digital Channels.
|ComingSoon=No
|Section={{Section
|sectionHeading=API Overview
|alignment=Vertical
|structuredtext=When a consumer sends a message, the third-party system must send a POST request to deliver the message to the agent in Digital Channels chat. In return, the agent’s response is delivered to the third-party system through a webhook that Digital Channels sends as a POST request. The third-party system may also send notifications about errors and different types of receipts.

{{NoteFormat|Contact your Genesys representative to configure webhooks for Digital Channels.|}}

Digital Channels requires the third-party system to respond to webhooks as follows:

*Send a response to the webhook within 10 seconds.
*The response for processed webhooks must have a 2XX HTTP code. We recommend '''200 OK'''. The '''201 Accepted''' code is reserved for when Digital Channels supports multiple messages per webhook.
*The response body should contain the <code>messageId</code> field with the unique identifier of the message. Digital Channels uses this ID when it processes delivery receipts to find the message in the history and possibly update its status.
*The response for webhooks that cannot be processed right now but should be redelivered must have a 5XX HTTP code. Digital Channels tries to redeliver the webhook according to the configuration for retry timeout and retry attempts. Contact your Genesys representative for details about this configuration.

The webhook POST request contains an X-Hub-Signature header with the SHA1 signature of the post payload. The signature is calculated using the keyed-hash message authentication code (HMAC), where the key is the app secret. The signature is then prefixed with <code>sha1=</code>. The third-party system should verify this signature to validate the integrity and origin of the payload.
|Status=No
}}{{Section
|sectionHeading=API Details
|alignment=Vertical
|structuredtext=Find the API requests, responses, and details here:

* {{Link-SomewhereInThisVersion|manual=WebAPIs|topic=Third-party_messaging}}
* {{Link-SomewhereInThisVersion|manual=WebAPIs|topic=Third-party_messaging_webhook}}
|Status=No
}}{{Section
|sectionHeading=Getting Started
|alignment=Vertical
|structuredtext=Make sure to check out the {{Link-SomewhereInThisVersion|manual=WebAPIs|topic=Getting_started}} page for more information about core concepts in the Engage Cloud APIs, such as requests and responses.
|Status=No
}}{{Section
|sectionHeading=Example: SMS data flow
|alignment=Horizontal
|Media=Image
|image=Pecapi-smsflow.png
|structuredtext=====1. Message API request====
<source lang="text">POST /channels/0123456789/messages HTTP/1.1
x-ccid: 0ff723ff-6c6f-44e0-9ce3-ce579337eadd
X-Hub-Signature: sha1=9577d7a3922516701c2e14ca043145eb2057b803

{
"messages": [
{
"channel": {
"from": {
"id": "16504661149"
},
"to": {
"id": "0123456789"
}
},
"type": "Text",
"text": "Consumer message text"
}
]
}
</source>

====2. Message API response====
<source lang="text">{
"status": {
"code": 0
},
"data": {
"ids": [
"1613473893265-0"
]
}
}
</source>

====3. Message Webhook request====
<source lang="text">POST / HTTP/1.1
X-Hub-Signature: sha1=20a00a8efbe06a43e403e1975873930a027a8f67
X-B3-TraceId: 05bb858a-3468-4c82-a8ce-3b1a9c4e4b67

{
"channel": {
"id": "0123456789",
"type": "sms",
"from": {
"id": "0123456789"
},
"to": {
"id": "16504661149"
},
"messageId": "1613474523265-0"
},
"type": "Text",
"text": "Agent message text"
}
</source>

====4. Message Webhook response====
<source lang="text">{
"messageId": "1613474523265-0"
}
</source>

====5. Receipt API request====
<source lang="text">POST /channels/0123456789/messages HTTP/1.1
x-ccid: 0ff723ff-6c6f-44e0-9ce3-ce579337eadd
X-Hub-Signature: sha1=8d9652cea2d2289ae76fc8b870b96598c6d94b05

{
"messages": [
{
"channel": {
"from": {
"id": "0123456789"
},
"to": {
"id": "16504661149"
},
"messageId": "1613474523265-0"
},
"type": "Receipt",
"status": "Delivered"
}
]
}
</source>

====6. Receipt API response====
<source lang="text">{
"status": {
"code": 0
}
}</source>
|Status=No
}}{{Section
|sectionHeading=Example: Email data flow
|alignment=Horizontal
|Media=Image
|image=Pecapi-emailflow.png
|structuredtext=====1. Email Webhook request====
<source lang="text">POST / HTTP/1.1
X-Hub-Signature: sha1=0959a2a00f3f57075d06094e5d9cdc32128f9ec8
X-B3-TraceId: 5767ea58-1511-4a98-bc56-7f34c43e3a51

{
"channel": {
"id": "company.com",
"type": "email",
"from": {
"id": "no-reply@company.com",
"name": "Sender display name"
},
"to": [
{
"id": "recipient-1@mail.com",
"name": "First Recipient"
},
{
"id": "recipient-2@mail.com",
"name": "Second Recipient"
}
],
"messageId": "f7acbac6-68db-4031-aec2-4bbd02627c4b",
"context": {
"replyTo": {
"id": "reply-to@company.com",
"name": "Responder display name"
}
}
},
"type": "Email",
"subject": "Subject",
"content": [
{
"type": "text",
"text": "Plain text email body"
},
{
"type": "html",
"text": "Html email body"
}
]
}
</source>

====2. Email Webhook response====
<source lang="text">{
"messageId": "f7acbac6-68db-4031-aec2-4bbd02627c4b"
}
</source>

====3. Receipt API request====
<source lang="text">POST /channels/company.com/messages HTTP/1.1
x-ccid: 0ff723ff-6c6f-44e0-9ce3-ce579337eadd
X-Hub-Signature: sha1=f6d8c023c909270eb2d50abdf519151dc80e128a

{
"messages": [
{
"channel": {
"from": {
"id": "no-reply@company.com"
},
"to": {
"id": "recipient-1@mail.com"
},
"messageId": "f7acbac6-68db-4031-aec2-4bbd02627c4b"
},
"type": "Receipt",
"status": "Failed",
"reasons": [
{
"code": 350,
"message": "Message not allowed. Your account has been suspended."
}
]
}
]
}
</source>

====4. Receipt API response====
<source lang="text">{
"status": {
"code": 0
}
}</source>
|Status=No
}}{{Section
|sectionHeading=Delivery receipts
|alignment=Vertical
|structuredtext=The third-party system can use delivery receipts to notify Digital Channels about delivery status or errors sending content messages. For usage examples, see the requests payload above for messages with <code>type="Receipt"</code>.

The following table describes possible values of the <code>status</code> field.
{{{!}} class="wikitable"
!Status
!Description
{{!}}-
{{!}}Delivered
{{!}}The message was delivered to the recipient.
{{!}}-
{{!}}Removed
{{!}}A previously published message was removed.
{{!}}-
{{!}}Failed
{{!}}The message was not delivered.
{{!}}}
If <code>status="Failed"</code>, the third-party system can attach a reason code and an optional message to the <code>reasons</code> field of the message.

The following table describes possible values of failure reason codes.
{{{!}} class="wikitable"
!Reason code
!Description
{{!}}-
{{!}}305
{{!}}The message has expired.
{{!}}-
{{!}}310
{{!}}Rate limit reached.
{{!}}-
{{!}}350
{{!}}Message not allowed.
{{!}}-
{{!}}510
{{!}}Unsupported message.
{{!}}-
{{!}}512
{{!}}Unknown message.
{{!}}-
{{!}}520
{{!}}Invalid message structure.
{{!}}-
{{!}}530
{{!}}Invalid destination.
{{!}}-
{{!}}500
{{!}}General error.
{{!}}}
|Status=No
}}
}}

PEC-Developer/Current/WebAPIs/Third-Party Messaging API - Revision history

WikiSysop: Created page with "{{Article |Standalone=No |DisplayName=Third-Party Messaging Overview |Context=The Third-Party Messaging API delivers messages between external messaging services (such as SMS..."