Intro to SDK Objects

Last updated: 2023-02-08

Contributors

Currently the SDK defines 6 types of objects:

Messages: publicly available messages exchanged between any number of users. Examples: blog comments, forum posts.
PrivateMessages: messages between 2 or more users that cannot be seen by others. Examples: direct messages on Twitter.
Threads: provide a way to structure the messages. Examples: blog posts, forum threads. Not mandatory (eg. Twitter).
Users: every other object type must have an author. This is the only object type that has no actions available.
Status: provides a way to update messages and private messages, like marking them as read. Only used in Send API
Typing: provides a way of notifying Engage Digital that an end-user is currently typing a message. Only used in Send API

Messages

We ignore extra fields and you only need to provide fields marked as required. Also, we consider a nulled field, an empty set, and the absence of a field as the same thing. Contents without required fields will be ignored.

Name	Type	Description
actions	Array	Possible actions for this content. Example: `["show", "reply"]`
attachments	Array	*Required unless body is present. An array of objects containing the url or a base64 content and the associated filename for each attachment*. Example: `[{ "url": "https://www.ringcentral.com/brand.png" }]` or `[{ "content": "iVBORw0KGgoAAAANSUhEUgAAAfUAAAH2CAIAAAD", "filename": "master.jpg" }]`
author	Hash	*Required* An User object.
body	String	*Required unless attachments are present.* Maximum size is 20k characters.
categories	Array	Example: `["TV", "Internet"]`
created_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)
context_data	Hash	A hash having the (expected) form: {'fieldname' => 'value'}. The keys must be [a-zA-Z-]. Example: `{"country": "Germany", "age": "34", "fruits": ["Apple", "Pear"]}`
display_url	String	A full URI where anyone can see the specific comment.
format	String	html or text. Default on html if not specified.
id	String	*Required*
in_reply_to_id	String	It has to be a valid content ID if present.
ip	String	Example: `1.2.3.4`
language	String	Example `en`
structured_content	Hash	*Optional.* Please keep in mind that an author used for structured content creation must be marked as a "puppet" identity and configured as a controlled identity in Engage Digital. Example: Structured contents.
structured_reply	Hash	*Optional.* Can be used when object is a reply to a structured content with a payload. Example: `{ payload: "DEFINED_PAYLOAD" }`
thread_id	String	*Required* If the option `messages.unthreaded` is set this field will be ignored.
updated_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)

** For .mp4 attachments you can disambiguate the type ("audio" or "video") by specifying it in the object. Example: { "url": "https://www.ringcentral.com/song.mp4", "type": "audio" }

When we post a message, we'll send the following attributes:

Name	Type	Description
attachments	Array	Example: `[{ "url": "https://www.ringcentral.com/brand.png", "type": "image", "filename": "brand.png" }]`
author_id	String
body	String
categories	Array
created_at	DateTime	Example: `2012-10-01T17:18:40Z`
format	String	Example: "text"
in_reply_to_id	String
sender_name	String	Example: "Jane from RingCentral"
structured_content	Hash	*Optional.* Example: Structured contents.
thread_id	String	Unless the `messages.unthreaded` option is set
updated_at	DateTime	Example: `2012-10-01T17:18:40Z`

PrivateMessages

Please note that private messages don't use threads, but are organized based on in_reply_to_id.

Name	Type	Description
actions	Array	Possible actions for this content.
attachments	Array	*Required unless body is present.* An array of objects containing the url or a base64 content and the associated filename for each attachment**. Example: `[{ "url": "https://www.ringcentral.com/brand.png" }]` or `[{ "content": "iVBORw0KGgoAAAANSUhEUgAAAfUAAAH2CAIAAAD", "filename": "master.jpg" }]`.
author	Hash	*Required* An User object.
body	String	*Required unless attachments are present.* Maximum size is 20k characters.
categories	Array	Example: `["TV", "Internet"]`
created_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)
context_data	Hash	A hash having the (expected) form: `{'fieldname' => 'value'}`. The keys must be [a-zA-Z-]. Example: `{"country": "Germany", "age": "34", "fruits": ["Apple", "Pear"]}`.
display_url	String	A full URI where anyone can see the specific comment.
format	String	html or text. Default on html if not specified.
id	String	*Required*
in_reply_to_id	String	It has to be a valid content ID if present.
ip	String	Example: `1.2.3.4`.
language	String	Example `en`.
recipient	Hash	*Required* An User object.
structured_content	Hash	*Optional.* Please keep in mind that an author used for structured content creation must be marked as a "puppet" identity and configured as a controlled identity in Engage Digital. Example: Structured contents.
structured_reply	Hash	*Optional.* Can be used when object is a reply to a structured content with a payload. Example: `{ payload: "DEFINED_PAYLOAD" }`
updated_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)

** For .mp4 attachments you can disambiguate the type ("audio" or "video") by specifying it in the object. Example: { "url": "https://www.ringcentral.com/song.mp4", "type": "audio" }

When we post a private message, we'll send the following attributes:

Name	Type	Description
attachments	Array	Example: `[{ "url": "https://www.ringcentral.com/brand.png", "type": "image", "filename": "brand.png" }]`
author_id	String
body	String
categories	Array
created_at	DateTime	Example: `2012-10-01T17:18:40Z`
format	String	Example: "html"
id	String
in_reply_to_id	String
ip	String
sender_name	String	Example: "Jane from RingCentral"
recipient_id	String
structured_content	Hash	*Optional.* Example: Structured contents.
updated_at	DateTime	Example: `2012-10-01T17:18:40Z`

Threads

Name	Type	Description
actions	Array	Possible actions for this content. Example: `["show", "reply"]`.
author	Hash	*Required* unless no_content option activated.
body	String	*Required* unless no_content option activated. Maximum size is 20k characters.
categories	Array	Example: `["TV", "Internet"]`
created_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)
context_data	Hash	A hash having the (expected) form: `{'fieldname' => 'value'}`. The keys must be [a-zA-Z-]. Example: `{"country": "Germany", "age": "34", "fruits": ["Apple", "Pear"]}`.
display_url	String	A full URI where anyone can see the specific comment.
format	String	html or text. Default on html if not specified.
id	String	*Required*
ip	String	Example: `1.2.3.4`.
title	String
updated_at	DateTime	Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601)

When we post a thread, we'll send the following attributes:

Name	Type	Description
attachments	Array	Example: `[{ "url": "https://www.ringcentral.com/brand.png", "type": "image", "filename": "brand.png" }]`
author_id	String
body	String
categories	Array
created_at	DateTime	Example: `2012-10-01T17:18:40Z`
format	String	Example: "text"
id	String
sender_name	String	Example: "Jane from RingCentral"
title	String
updated_at	DateTime	Example: `2012-10-01T17:18:40Z`

Users

Name	Type	Description
id	String	*Required*, ID of the author on the third party system (yours). User with the same ID will be considered to be the same identity in Engage Digital.
firstname	String	Firstname of the user if you can provide it.
lastname	String	Lastname of the user if you can provide it.
screenname	String	*Required* Name we display for this user.
avatar_url	String
email	String	Confirmed email of the user, can be used to send email PM if no PM mechanism is supported.
home_phone	String	Home phone number.
mobile_phone	String	Mobile/cellular phone number.
created_at	DateTime	*Required* Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601).
updated_at	DateTime	*Required* Supported formats: `2012-02-10`, `2012-10-01T17:18:40Z` (ISO 8601).
puppetizable	Boolean	Whether Engage Digital can use this user as identity to create message. False by default.
gender	String	Accepted values are "`man`" or "`woman`".
context_data	Hash	Data specific to the User, that will be stored in Engage Digital at the identity and identitygroup level. Expect a hash having the (expected) form: `{'field_name' => 'value'}`. The keys must be [a-zA-Z-]. Example: {`"country": "Germany", "age": "34", "fruits": ["Apple", "Pear"]}`.

Status

We ignore extra fields and you only need to provide fields marked as required. Used only in Send API

Name	Type	Description
id	String	*Required*, ID of the message or private message on the third party system (yours). This is the ID you return on `message.create` and `private_message.create` actions

Typing

We ignore extra fields and you only need to provide fields marked as required. Can only be used if the messaging.typing_indicator option is enabled (see Options). Used only in Send API

Name	Type	Description
thread_id	String	*Required if `in_reply_to_id` is not provided*, ID of the thread on the third party system (yours). Will be used in priority over `in_reply_to_id` if both are provided.
in_reply_to_id	String	*Required if `thread_id` is not provided*, ID of the message or private message on the third party system (yours). This is the ID you return on `message.create` and `private_message.create` actions
preview	String	*Required for `typing.start` event only*, preview of the message being typed by the end user