POST /ott/v1/send

Send an OTT message to the recipient. Supported OTT networks are Facebook Messenger and LINE.

JSON Parameters 
NameTypeDescription
messageKeystringRequired. User-defined message identifier.
messageGroupKeystringUser-defined message identifier to group a number of send requests.
fromobjectRequired. Object containing the senderType and senderId.
from.senderTypestringRequired. Indicates the name of the OTT network the resource is being registered with values: line, messenger.
from.senderIdstringRequired. Indicates the identifier of the OTT resource sending the message: LINE Channel Id, Messenger Page Id.
toobjectRequired. Message Recipient details. For Messenger: Either ottId or userReference is required. If both ottId and userReference are provided, userReference is used for the send request. For LINE: ottId is required. If both ottId and userReference are provided, userReference is used for send request.
to.ottIdstringRecipient ID of the user. For LINE, if userReference is invalid, a retry is attempted with ottId as senderId.
to.userReferencestringAlternate Recipient ID of the user. For Messenger: user_ref can be passed as userReference. For LINE, reply_token can be passed as userReference.
messageobjectRequired. Message contents of the send request.
message.subjectstringMessage name
message.contentsarrayRequired. Message content blocks of the send message request. For messenger, only 1 content block is allowed. For LINE, upto 5 content blocks are allowed.
message.contents.typestringRequired. Indicates the message content type of the send request with values: text, image, audio, video, native.
message.contents.textstringMessage text to be sent out to the recipient. Required for ‘text’ type message content.
message.contents.urlstringURL of the multimedia attachment to be sent out to the recipient. Required for ‘image, audio, video’ type message content.
message.contents.altUrlstringAlternate URL of the multimedia attachment to be sent out to the recipient. Required for LINE for ‘image, video’ type message content.
message.contents.durationstringLength of the audio multimedia attachment to be sent out to the recipient. Required for LINE for ‘audio’ type message content.
message.contents.nativePayloadobjectOtt-network-specific blob of JSON payload passed in message request.
message.contents.isReusablebooleanIndicates if a multimedia attachment can be reused for future messages. Only supported for Messenger.
message.contents.attachmentIdstringAttachment Id of a reusable multimedia asset. Only supported for Messenger.
message.customKeysarrayCustom keys to pass-through in the message payload.
message.customKeys.messagingTypestringIndicates the messaging_type of a messenger send request with values: RESPONSE, UPDATE, MESSAGE_TAG. Required for Messenger send requests.
message.customKeys.tagstringMessage Tag of a messenger send request. Required for Messenger send request if messagingType = Message_TAG.
message.customKeys.notificationTypestringIndicates the push notification type for message send request with values: REGULAR, SILENT_PUSH, NO_PUSH. Required for Messenger. Optional for Messenger send requests.
validityPeriodstringRequired. Time period for which the request is valid.

Responses 
StatusNameTypeDescription
201  Created
 ottRequestIdguidThe ID of the send message request which can also be used to retrieve the message send details.
    
400  Bad Request
 messagestringError message.
 errorcodenumberError code.
 documentationstringDocumentation for the error code.
 validationErrorsarrayValidation errors in the request payload.
    
403  Forbidden
 messagestringError message.
 errorcodenumberError code.
 documentationstringDocumentation for the error code.
    
404  Not Found
 messagestringError message.
 errorcodenumberError code.
 documentationstringDocumentation for the error code.

Usage 

Example Request: Messenger Message Send 
  • For the to object, either ottId or userReference is required. If both ottId and userReference are provided, userReference is used for send request.
  • The message.contents array can’t contain more than 1 object.
  • For the message.customKeys array, messagingType is required. If the messagingType is MESSAGE_TAG, then message.customKeys.tag is required. notificationType is an optional custom key.
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20                "type": "text",
21                "text": "thanks for purchase"
22        }],
23        "customKeys": [{
24            "messagingType": "RESPONSE"
25        }]
26    },
27    "validityPeriod": 30
28}

Example Request: LINE Message Send 
  • For the to object, ottId is required. If both ottId and userReference are provided, userReference is used for send request. If userReference is invalid, a retry is attempted with ottId as senderId.
  • The message.contents array can contain up to 5 content objects.
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "CanBeAGUIDorAny100UnicodeCharString",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "line",
11        "senderId": "2145435435632435"
12    },
13    "to": {
14        "ottId": "U42348yafsd8y3248yfsq8cy9088934d",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20                "type": "text",
21                "text": "Thanks for purchase"
22        }],
23        "customKeys": [{
24            "messagingType": "RESPONSE"
25        }]
26    },
27    "validityPeriod": 30
28}

Example Success Response 

 
1HTTP/1.1 201 Created
2
3{
4    "ottRequestId": "w5f397e-3464-53h6-4535-5345359f567h546"
5}

Example Error Response 

 
1HTTP/1.1 400 Bad Request
2
3{
4    "message": "Please fix the following errors",
5    "errorcode": 10006,
6    "documentation": "",
7    "validationErrors": [
8        {
9            "message": "Message contents must be provided",
10            "errorcode": 10002,
11            "documentation": ""
12        }
13    ]
14}

Possible Errors 
MessageDetails
From object must be providedThe send message request payload is missing a from object.
Sender Id must be providedsenderId is empty or missing in the from object in the send message request payload.
Sender Type must be providedsenderType is empty or missing in the from object in the send message request payload.
Sender Id provided is either unregistered or inactive UnknownsenderId provided in the send message request payload is unregistered or inactive Unknown.
To object must be providedThe send message request payload is missing a to object.
Message object must be providedThe send message request payload is missing a message object.
Message contents must be providedThe send message request payload is missing a contents property within message object or contents array is empty.
Content Type for all message contents must be providedtype is empty or missing in at least one of the content objects in contents property within message object.
Text attribute must be provided for Text type Message Contenttext is empty or missing for a content object with type text in contents property within message object.
Url attribute must be provided for Image, File, Audio and Video type Message Contenturl is empty or missing for a content object with type image, audio, video, file in contents property within message object.
Validity Period must be providedvalidityPeriod is empty or missing in the from object in the send message request payload.
Message object can’t contain more than {0} message objectscontents array in message contains more objects that supported for a specific OTT network. For Messenger, contents array can’t contain more than 1 object. For LINE, contents array can’t contain more than 5 objects.
MessagingType must be provided as a Custom KeyMESSENGER only: messagingType property is empty or missing in customKeys.
Tag must be provided as a Custom Key when MessagingType is provided as MESSAGE_TAGMESSENGER only: tag property is empty or missing in customKeys, if the messagingType is set to MESSAGE_TAG.
Either OttId or UserReference must be provided in the To objectMESSENGER only: Both ottId and userReference are empty or missing in the to object in the send message request payload. At least one of the fields should be provided.
OttId must be provided in the To objectLINE only: ottId is empty or missing in the to object in the send message request payload.

Samples for Different Messenger Content Types 

Text Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20                "type": "text",
21                "text": "thanks for purchase"
22        }],
23        "customKeys": [{
24            "messagingType": "RESPONSE"
25        }]
26    },
27    "validityPeriod": 30
28}

Image Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "image",
21            "url": "https://example.com/original.jpg",
22            "alturl": "https://example.com/preview.jpg",
23            "isreusable": true,
24            "attachmentid": 12345
25        }],
26        "customKeys": [{
27            "messagingType": "RESPONSE"
28        }]
29    },
30    "validityPeriod": 30
31}

Video Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "video",
21            "url": "https://example.com/original.mp4"
22        }],
23        "customKeys": [{
24            "messagingType": "RESPONSE"
25        }]
26    },
27    "validityPeriod": 30
28}

Audio Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "audio",
21            "url": "https://example.com/original.m4a"
22        }],
23        "customKeys": [{
24            "messagingType": "RESPONSE"
25        }]
26    },
27    "validityPeriod": 30
28}

Native Message 

Use a native message content type to send an OTT network-specific content other than Text, Image, Audio, or Video. For Messenger, the native content type can be used to send File, Templates including Generic template, button template, receipt template, and list template. To send a native message, use a content type of native and provide the OTT network-specific message object into payload property.

For more information about Messenger sends, see the Facebook Messenger Send API Reference.

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7   "MessageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8   "From": {
9      "SenderType": "messenger",
10      "SenderId": "503868699681937"
11   },
12   "To": {
13      "OttId": "FBfacdb735074f7c492c0bf190fa99020"
14   },
15   "Message": {
16      "Subject": "Message Name",
17      "Contents": [
18         {
19            "type": "native",
20            "nativePayload": {
21               "attachment": {
22                  "type": "template",
23                  "payload": {
24                     "template_type": "generic",
25                     "elements": [
26                        {
27                           "title": "Welcome!",
28                           "image_url": "https://example.com/company_image.png",
29                           "subtitle": "We have the right hat for everyone.",
30                           "default_action": {
31                              "type": "web_url",
32                              "url": "https://example.com/view?item=103",
33                              "messenger_extensions": false,
34                              "webview_height_ratio": "tall",
35                              "fallback_url": "https://example.com/"
36                           },
37                           "buttons": [
38                              {
39                                 "type": "web_url",
40                                 "url": "https://example.com",
41                                 "title": "View Website"
42                              },
43                              {
44                                 "type": "postback",
45                                 "title": "Start Chatting",
46                                 "payload": "DEVELOPER_DEFINED_PAYLOAD"
47                              }
48                           ]
49                        }
50                     ]
51                  }
52               }
53            }
54         }
55      ],
56      "CustomKeys": [
57         {
58            "messagingType": "RESPONSE"
59         }
60      ]
61   },
62   "ValidityPeriod": 30
63}

Samples for Different LINE Content Types 

Text Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "line",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20                "type": "text",
21                "text": "thanks for purchase"
22        }],
23        "customKeys": []
24    },
25    "validityPeriod": 30
26}

Image Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "line",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "image",
21            "url": "https://example.com/original.jpg",
22            "alturl": "https://example.com/preview.jpg"
23        }],
24        "customKeys": []
25    },
26    "validityPeriod": 30
27}

Video Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "line",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "video",
21            "url": "https://example.com/original.mp4",
22            "alturl": "https://example.com/preview.jpg"
23        }],
24        "customKeys": []
25    },
26    "validityPeriod": 30
27}

Audio Message 

 
1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "messenger",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "audio",
21            "url": "https://example.com/original.m4a",
22            "duration": 13141
23        }],
24        "customKeys": []
25    },
26    "validityPeriod": 30
27}

Native Message 

Use a native message content type to send an OTT network-specific content other than Text, Image, Audio, or Video. For LINE, the native content type can be used to send Sticker, Location, ImageMap, Button Template, Confirm Template, Carousal Template and Image Carousal Template. To send a native message, use a content type of native and provide the OTT network-specific message object into payload property.

For more information about LINE sends, see the LINE API Reference.

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /ott/v1/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "messageKey": "e1c35141-6e5c-4bc2-813b-60f969e52b0d",
8    "messageGroupKey": "CanBeAGUIDorAny100UnicodeCharString",
9    "from": {
10        "senderType": "line",
11        "senderId": "503868699681937"
12    },
13    "to": {
14        "ottId": "FBfacdb735074f7c492c0bf190fa99020",
15        "userReference": "1938cd4d34cc4db0b109756b8a9b14ff"
16    },
17    "message": {
18        "subject": "Message Name",
19        "contents": [{
20            "type": "native",
21            "payload": {
22                   "type": "template",
23                   "altText": "this is a buttons template",
24                   "template": {
25                       "type": "buttons",
26                       "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
27                       "title": "Menu",
28                       "text": "Please select",
29                       "actions": [{
30                               "type": "postback",
31                               "label": "Buy",
32                               "data": "action=buy&itemid=123"
33                           },
34                           {
35                               "type": "postback",
36                               "label": "Add to cart",
37                               "data": "action=add&itemid=123"
38                           },
39                           {
40                               "type": "uri",
41                               "label": "View detail",
42                               "uri": "http://example.com/page/123"
43                           }
44                       ]
45                   }
46               }
47           }],
48        }],
49        "customKeys": []
50    },
51    "validityPeriod": 30
52}

Summary
Address
Approvals
Assets
Audits
Auth
Automation Studio
Bulk Data Ingest
Campaigns
Chat Messaging
Send Message to Recipient
Retrieve Sent Message by MessageId
Register OTT Property
Retrieve Registration Property by Platform and Id
Retrieve Registration Collection by Platform
Contacts
Data Extensions
Data Extension Data
Data Extension Imports
Data Extension Rows (Asynchronous)
Data Extension Rows (Synchronous)
Domain Verification
Event Notification
File Transfer Locations
Journeys and Events
Messaging
Nested Tags
Platform
Push
Security
Seed List
SMS
Transactional Messaging - Email
Transactional Messaging - Push
Transactional Messaging - OTT
Transactional Messaging - SMS
Workflow Teams
REST API Permission IDs and Scopes

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!