Inbound Conversations

The Inbound Conversations Data Action allows you to programmatically handle the creation of a new conversation, including:

Sending auto response messages
Assigning one or more Spoke users to manage the conversation
Updating the conversation name

A Conversation in Spoke is a thread of messages between a group of two or more participants. Participants can be on external channels, such as SMS or WhatsApp, or internal channels, such as user of Spoke application. External participants connect to a conversation through an SMS or WhatsApp enabled number. Internal participants connect using the Spoke application.

This Data Action is invoked when a new conversation is created from an incoming message from a participant on an external channel. A new conversation is created when a message is received from an external contact that is not already involved in an active conversation with the given company number.

Implementing this data action allows you to define which Spoke Users (if any) are responsible for managing the conversation, as well as optionally sending an auto response to the external participant. Once a conversation is created, this Data Action will not be invoked again for the contact number/company address pair, until the active conversation is closed.

Note: Spoke uses the Twilio Conversations API to support conversational messaging in the Spoke application. The Data Action(s) documented here extend the functionality of the Conversations API to enable routing, shared inbox functionality and auto response management. You can read more about Twilio's conversations API here.

Below are the settings that can be controlled via Inbound Conversations Data Action.

Auto Response

Allows an auto response message to be sent to the external contact. Use this to automatically respond to the external contact without waiting for a user to respond.

On top of normal auto response scenarios such as Thanks for your message, we'll be with you shortly, the auto response feature can be used for scenarios where you do not want your users handling a conversation, for example:

Profanity in the incoming message
Time of day
A closed or unmonitored service channel

Routing Action

Defines whether a conversation is to be routed to Spoke users via assign or not routed via donotroute.

If a conversation is set to donotroute then no Spoke users will be assigned to the conversation. The conversation will be closed, and because no internal participants are assigned the external contact will not receive any response, unless the auto response feature is also used.

Assign Users

Allows one or more Spoke users to be assigned to the conversation. This allows you to fine tune which users are added to a specific conversation. You can add more than one user, and all users can actively participate in the conversation.

Each user is identified by their email address in Spoke. Invalid emails are ignored.

Conversation Name

Allows a name to be assigned to a conversation. Use this to provide more context to your Spoke users about the conversation. The name will appear in the conversation list in the Spoke application, and will be used as the title for any push notifications that are sent to users' devices when new messages are added to the conversation.

Claim Rule

Allows a claim rule to be assigned to a conversation. Claiming a conversation requires a single team member to 'claim' ownership of the conversation. When a conversation is claimable, a 'Claim Conversation' button displays in the Spoke application. Once claimed, all other team members are removed from the conversation.

Close Timer

Allows a close timer to be set to a conversation. Use this to control how long the conversation will remain open before being automatically closed by the system. The timer is reset any time a conversation is updated, including adding new messages.

Specify the timer value in ISO8601 duration format.

Passthrough Parameters

Sets the passthrough parameters associated with the conversation. See Passthrough Parameters for the full picture of how they are set and returned.

The maximum size of passthrough parameters is 1000 bytes. If this limit is exceeded, then the passthrough parameters from the response will be discarded.

Request and Response

Spoke sends an HTTP GET request with the parameters defined in the Inbound Conversations Request Payload, and expects an Inbound Conversations Response within 2 seconds. If no response payload is returned, the call will proceed as planned, using the original configuration for the call.

If the request returns a non-200 response or times out and the fallback URL is configured, Spoke will send another request to the fallback URL with the same payload.

If no response payload is returned, the conversation will proceed as planned, using the original configuration for the given company address. This means that:

Messages to an assigned SMS enabled DDI will be routed to the assigned users
Company numbers or addresses that are unassigned will not have any users added to the conversation, and the conversation will be automatically closed

Inbound Conversations request

POST

https://your-data-action-endpoint.example.com

/inbound-conversations

Spoke sends this request to the Data Action URL you configure.

Inbound Conversations request › Request Body

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: channel, companyAddress, contactAddress +3 more
	type = object · requires: channel, companyAddress, contactAddress +3 more
	type = object · requires: authorContactAddress, channel, companyAddress +4 more

Properties for sms:

InboundSmsConversationsDataActionRequestPayload

channel

string · const · required

The channel of the inbound conversation.

The value for this field will always be sms, signifying that the conversation was originated by an inbound SMS message from a single contact address to a company address

Const value: sms

companyAddress

string · required

The company number that the conversation was routed to. This will be one of the numbers defined in the Spoke Phone Number settings page.

The value for this field will always be a phone number in +E164 format (e.g. +16508221060)

contactAddress

string · required

The address of the external party that originated the conversation.

The value for this field will always be a phone number in +E164 format (e.g. +16508221060)

conversationId

string · required

The Spoke ID of the conversation

MessageContent · required

The content of the message

vendorConversationId

string · required

The vendor's identifier for the conversation

contactDisplayName

string

The display name of the phonebook contact (if any) associated with the external party on the call.

contactId

string

The ID of the phonebook contact (if any) associated with the external party on the call.

Inbound Conversations request › Responses

200

Return the payload below within 2 seconds.

InboundConversationsDataActionResponsePayload

assignUsers

string[]

List of users to be added to the conversation. Required when routingAction is assign.

Each user is identified by their email address in Spoke. Invalid email addresses are ignored.

For numbers assigned to a team shared inbox, if there are no valid emails in the assignUsers payload, the users associated with the team will be assigned to the conversation.

A conversation can have up to 10 participants and users will be added to the conversation until this limit is reached.

AutoResponseContent

Returning this parameter will create an auto response message that will be added to the conversation. All participants will see the response content.

claimRule

string · enum

Defines whether a conversation can be claimed by a Spoke user. Claiming allows a user to take exclusive ownership of a conversation. Once claimed, other Spoke participants will be removed from the conversation.

For numbers assigned to a team shared inbox, if no value is provided, then the setting for the team shared inbox will apply.

Possible values:

claimable: The conversation can be claimed at any time by any user assigned to the conversation
not_claimable: The conversation is not claimable
required_before_reply: A variant of claimable, this requires the conversation to be claimed before a reply can be sent to the external participant

Enum values:

claimable

not_claimable

required_before_reply

closeTimer

string

Set this value to control how long the conversation will remain open before being automatically closed by the system. The timer is reset any time a conversation is updated, including adding new messages.

Specify the timer value in ISO8601 duration format. For example, to automatically close a conversation:

After 12 hours: PT12H
After 30 days: P30D
After 3 months: P3M

The following are the minimum and maximum values for the field:

Minimum Value: 600 seconds (PT600S)
Maximum Value: 180 days (P180D)

name

string

Name of the conversation. Can be up to 100 characters long.

passthroughParameters

ConversationPassthroughParametersResponse

If specified, stores the passthrough parameters against the conversation.

Each passthrough parameter key must start with the prefix x- and the value must be a string. Otherwise, the parameter will be ignored.

The maximum size of passthrough parameters is 1000 bytes.

Example:


Code
{
  "x-contactId": "HS12345",
  "x-orderId": "ORD12345"
}

routingAction

string · enum

How the conversation should be handled - assign or donotroute

assign: Assign the message to one or more Spoke users, if this value is set, then assignUsers is required

donotroute: Do not assign any users. The conversation will remain open however no additional participants will be added to the conversation. You can use this option to block an incoming message due to content, profanity etc.

Enum values:

assign

donotroute

POST/inbound-conversations

curl https://your-data-action-endpoint.example.com/inbound-conversations \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "channel": "sms",
  "companyAddress": "companyAddress",
  "contactAddress": "contactAddress",
  "contactDisplayName": "contactDisplayName",
  "contactId": "contactId",
  "conversationId": "conversationId",
  "messageContent": {
    "body": "body",
    "media": [
      {
        "fileSize": 0,
        "mimeType": "mimeType",
        "tempUrl": "tempUrl"
      }
    ]
  },
  "vendorConversationId": "vendorConversationId"
}'

Example Request Body

{
  "channel": "sms",
  "companyAddress": "companyAddress",
  "contactAddress": "contactAddress",
  "contactDisplayName": "contactDisplayName",
  "contactId": "contactId",
  "conversationId": "conversationId",
  "messageContent": {
    "body": "body",
    "media": [
      {
        "fileSize": 0,
        "mimeType": "mimeType",
        "tempUrl": "tempUrl"
      }
    ]
  },
  "vendorConversationId": "vendorConversationId"
}

json

Example Responses

{
  "assignUsers": [
    "string"
  ],
  "autoResponseContent": {
    "author": "author",
    "body": "body"
  },
  "claimRule": "claimable",
  "closeTimer": "closeTimer",
  "name": "name",
  "passthroughParameters": {},
  "routingAction": "assign"
}

json

application/json

Insights

Request and Response

If the request returns a non-200 response or times out and the fallback URL is configured, Spoke will send another request to the fallback URL with the same payload.

If no response payload is returned, the conversation will proceed as planned, using the original configuration for the given company address. This means that:

Messages to an assigned SMS enabled DDI will be routed to the assigned users

Company numbers or addresses that are unassigned will not have any users added to the conversation, and the conversation will be automatically closed

Inbound Conversations request

POST

https://your-data-action-endpoint.example.com

/inbound-conversations

Spoke sends this request to the Data Action URL you configure.

Inbound Conversations request › Request Body

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: channel, companyAddress, contactAddress +3 more
	type = object · requires: channel, companyAddress, contactAddress +3 more
	type = object · requires: authorContactAddress, channel, companyAddress +4 more

Properties for sms:

InboundSmsConversationsDataActionRequestPayload

channel

string · const · required

The channel of the inbound conversation.

The value for this field will always be sms, signifying that the conversation was originated by an inbound SMS message from a single contact address to a company address

Const value: sms

companyAddress

string · required

The company number that the conversation was routed to. This will be one of the numbers defined in the Spoke Phone Number settings page.

The value for this field will always be a phone number in +E164 format (e.g. +16508221060)

contactAddress

string · required

The address of the external party that originated the conversation.

The value for this field will always be a phone number in +E164 format (e.g. +16508221060)

conversationId

string · required

The Spoke ID of the conversation

MessageContent · required

The content of the message

vendorConversationId

string · required

The vendor's identifier for the conversation

contactDisplayName

string

The display name of the phonebook contact (if any) associated with the external party on the call.

contactId

string

The ID of the phonebook contact (if any) associated with the external party on the call.

Inbound Conversations request › Responses

200

Return the payload below within 2 seconds.

InboundConversationsDataActionResponsePayload

assignUsers

string[]

List of users to be added to the conversation. Required when routingAction is assign.

Each user is identified by their email address in Spoke. Invalid email addresses are ignored.

For numbers assigned to a team shared inbox, if there are no valid emails in the assignUsers payload, the users associated with the team will be assigned to the conversation.

A conversation can have up to 10 participants and users will be added to the conversation until this limit is reached.

AutoResponseContent

Returning this parameter will create an auto response message that will be added to the conversation. All participants will see the response content.

claimRule

string · enum

For numbers assigned to a team shared inbox, if no value is provided, then the setting for the team shared inbox will apply.

Possible values:

claimable: The conversation can be claimed at any time by any user assigned to the conversation
not_claimable: The conversation is not claimable
required_before_reply: A variant of claimable, this requires the conversation to be claimed before a reply can be sent to the external participant

Enum values:

claimable

not_claimable

required_before_reply

closeTimer

string

Specify the timer value in ISO8601 duration format. For example, to automatically close a conversation:

After 12 hours: PT12H
After 30 days: P30D
After 3 months: P3M

The following are the minimum and maximum values for the field:

Minimum Value: 600 seconds (PT600S)
Maximum Value: 180 days (P180D)

name

string

Name of the conversation. Can be up to 100 characters long.

passthroughParameters

ConversationPassthroughParametersResponse

If specified, stores the passthrough parameters against the conversation.

Each passthrough parameter key must start with the prefix x- and the value must be a string. Otherwise, the parameter will be ignored.

The maximum size of passthrough parameters is 1000 bytes.

Example:


Code
{
  "x-contactId": "HS12345",
  "x-orderId": "ORD12345"
}

routingAction

string · enum

How the conversation should be handled - assign or donotroute

assign: Assign the message to one or more Spoke users, if this value is set, then assignUsers is required

Enum values:

assign

donotroute