Conversations

Conversations represent long-running message threads between a Spoke user with an SMS enabled DDI and a customer of your organisation.

Send a new conversation message

POST

https://integration.spokephone.com

/conversationMessages

Sends a new SMS or Group MMS message to one or more contacts. The message is associated with a conversation owned by either a Spoke Team or a Spoke Member, identified via the sender field. If a conversation between the company number and the contact address(es) exists, the message will be added to it; otherwise a new conversation is created. Note that as a result of this request being successfully processed, a conversation.message.created webhook event will be generated.

Send a new conversation message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new conversation message › Request Body optional

CreateConversationMessageBody

contactAddresses

string[] · required

The numbers of the contacts to send the message to. Must be in +E164 format.

If more than one contact address is provided, the message is sent as a Group MMS message.

CreateMessageContent · required

CreateConversationMessageSender · required

Identifies which phone number the message is sent from.

assignUsers

string[]

Required if routingAction is assign_users. A list of user email addresses to assign to the conversation. A conversation can have up to 10 participants and users will be added to the conversation until this limit is reached. Assignment behaviour depends on the value of routingAction:

assign_users: Only assign the users defined in the request payload
assign_owner: Assign the users defined in the request payload in addition to the owner's users.

claimRule

string · enum

If provided, sets the claim rule for a newly created conversation. The value is ignored if the conversation already exists.

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notificationMode

string · enum

Controls notification and unread indicators for API-delivered messages.

Defaults to notify_unread.

Values:

notify_unread: Sends a system notification and keeps the message unread. Use for messages that need immediate attention.
silent_unread: Suppresses system notifications and keeps the message unread. Use for bulk messages that users can check later.
silent_read: Suppresses system notifications and marks the message as read unless the conversation already has existing unread messages. Use for background delivery.

Enum values:

notify_unread

silent_read

silent_unread

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

If the conversation already exists and has passthrough parameters, the new parameters will be merged with the existing parameters. If a key exists in both the existing passthrough parameters and the new passthrough parameters, the new parameter value will overwrite the existing value.

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

routingAction

string · enum

Defines whether to assign users to the conversation that is created as a result of the message.

Possible values:

assign_users: Assign the conversation to one or more Spoke users. If this value is used, the assignUsers parameter must be non-empty
do_not_route: Do not assign any Spoke users to the conversation. If the customer replies, no one will be able to respond to the customer
assign_owner: Assign the conversation to the owner of the company address. Currently supports team and member owners only.

Enum values:

assign_owner

assign_users

do_not_route

Send a new conversation message › Responses

Successfully sent the message

CreateConversationMessageResponse

hasExistingConversation

boolean · required

Indicates whether the conversation already existed before this message was sent. If true, the message was added to an existing conversation. If false, a new conversation was created for this message.

vendor

string · enum · required

The CPaaS vendor that carried the message. One of the following values:

twilio

Enum values:

twilio

vendorConversationId

string · required

The vendor's identifier of the conversation associated with the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the ConversationSid of the conversation

vendorMessageId

string

The vendor's identifier of the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the MessageSid of the message

This field will be undefined if a new Group MMS conversation was created for this message. In this case, you should subscribe to the conversation.message.created webhook event to retrieve the message details when it is created asynchronously.

POST/conversationMessages

curl https://integration.spokephone.com/conversationMessages \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <string>' \
  --data '{
  "assignUsers": [
    "string"
  ],
  "claimRule": "claimable",
  "closeTimer": "closeTimer",
  "contactAddresses": [
    "string"
  ],
  "conversationName": "conversationName",
  "messageContent": {
    "author": "author",
    "body": "body",
    "sendAsUser": "sendAsUser"
  },
  "notificationMode": "notify_unread",
  "passthroughParameters": {},
  "routingAction": "assign_owner",
  "sender": {
    "companyAddress": "companyAddress",
    "type": "e164"
  }
}'

Example Request Body

{
  "assignUsers": [
    "string"
  ],
  "claimRule": "claimable",
  "closeTimer": "closeTimer",
  "contactAddresses": [
    "string"
  ],
  "conversationName": "conversationName",
  "messageContent": {
    "author": "author",
    "body": "body",
    "sendAsUser": "sendAsUser"
  },
  "notificationMode": "notify_unread",
  "passthroughParameters": {},
  "routingAction": "assign_owner",
  "sender": {
    "companyAddress": "companyAddress",
    "type": "e164"
  }
}

json

Example Responses

{
  "hasExistingConversation": true,
  "vendor": "twilio",
  "vendorConversationId": "vendorConversationId",
  "vendorMessageId": "vendorMessageId"
}

json

application/json

deprecated

Send a new SMS message

POST

https://integration.spokephone.com

/messages

DEPRECATED: This endpoint has been deprecated and will be removed in a future version of the API. Please use the POST /conversationMessages endpoint instead.

Sends a new SMS message to a number on behalf of a Spoke User. The Spoke user must have an SMS enabled DDI. If a conversation between the specified user and the number exists, the message will automatically be added to the conversation. If a conversation does not exist, a new one will be created containing the message. Note that as a result of this request being successfully processed, a conversation.message.created webhook event will be generated.

Send a new SMS message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new SMS message › Request Body optional

CreateMessageBody

body

string · required

The content of the message, can be up to 1,600 characters long

from

string · required

Either the user’s email address, or their SMS enabled DDI (in +E164 form). If an email address is provided, we will automatically use the user’s default SMS DDI

to

string · required

The recipient’s phone number in +E164 form, e.g. +61488881234 or +155512345678

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notifyUsers

boolean

Controls whether notifications for this message are sent to users.

When a conversation already exists between the company address and the contact address, setting notifyUsers to false will still notify the existing participants.

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Send a new SMS message › Responses

Successfully sent the message

CreateMessageResponse

success

boolean · required

deprecated

Send a new Team SMS message

POST

https://integration.spokephone.com

/teamMessages

DEPRECATED: This endpoint has been deprecated and will be removed in a future version of the API. Please use the POST /conversationMessages endpoint instead.

Sends a new SMS message to a number on behalf of a Spoke Team. The Spoke team must have an SMS enabled DDI. If a conversation between the specified team and the number exists, the message will automatically be added to the conversation. If a conversation does not exist, a new one will be created containing the message. Note that as a result of this request being successfully processed, a conversation.message.created webhook event will be generated.

Send a new Team SMS message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new Team SMS message › Request Body optional

anyOf

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

Decision Table

Variant	Matching Criteria
	type = object · requires: companyAddress, contactAddress, messageContent
	type = object · requires: channel, companyAddress, contactAddresses +1 more

Properties for CreateSmsTeamMessageBody:

CreateSmsTeamMessageBody

companyAddress

string · required

The company number to use as the sender Id. Must be in +E164 format.

contactAddress

string · required

The number of the contact to send the message to. Must be in +E164 format.

CreateMessageContent · required

assign_users: Only assign the users defined in the request payload
assign_team: Assign the users defined in the request payload in addition to the team’s users.

channel

string

The type of the conversation channel.

This field is optional and defaults to the sms channel if not provided. If provided, the value must be sms, signifying that the message is an SMS message to a single contact.

If provided, sets the claim rule for a newly created conversation. The value is ignored if the conversation already exists.

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notifyUsers

boolean

Controls whether notifications for this message are sent to users.

When a conversation already exists between the company address and the contact address(es), setting notifyUsers to false will still notify the existing participants.

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Defines whether to assign users to the conversation that is created as a result of the message.

Send a new Team SMS message › Responses

Successfully sent the message

CreateTeamMessageResponse

hasExistingConversation

boolean · required

vendor

string · enum · required

The CPaaS vendor that carried the message. One of the following values:

twilio

Enum values:

twilio

vendorConversationId

string · required

The vendor's identifier of the conversation associated with the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the ConversationSid of the conversation

vendorMessageId

string

The vendor's identifier of the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the MessageSid of the message

POST/teamMessages

curl https://integration.spokephone.com/teamMessages \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <string>' \
  --data '{
  "assignUsers": [
    "string"
  ],
  "channel": "channel",
  "claimRule": "claimable",
  "closeTimer": "closeTimer",
  "companyAddress": "companyAddress",
  "contactAddress": "contactAddress",
  "conversationName": "conversationName",
  "messageContent": {
    "author": "author",
    "body": "body",
    "sendAsUser": "sendAsUser"
  },
  "notifyUsers": true,
  "passthroughParameters": {},
  "routingAction": "assign_team"
}'

Example Request Body

{
  "assignUsers": [
    "string"
  ],
  "channel": "channel",
  "claimRule": "claimable",
  "closeTimer": "closeTimer",
  "companyAddress": "companyAddress",
  "contactAddress": "contactAddress",
  "conversationName": "conversationName",
  "messageContent": {
    "author": "author",
    "body": "body",
    "sendAsUser": "sendAsUser"
  },
  "notifyUsers": true,
  "passthroughParameters": {},
  "routingAction": "assign_team"
}

json

Example Responses

{
  "hasExistingConversation": true,
  "vendor": "twilio",
  "vendorConversationId": "vendorConversationId",
  "vendorMessageId": "vendorMessageId"
}

json

application/json

Calls Transcripts

Send a new conversation message

POST

https://integration.spokephone.com

/conversationMessages

Send a new conversation message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new conversation message › Request Body optional

CreateConversationMessageBody

contactAddresses

string[] · required

The numbers of the contacts to send the message to. Must be in +E164 format.

If more than one contact address is provided, the message is sent as a Group MMS message.

CreateMessageContent · required

CreateConversationMessageSender · required

Identifies which phone number the message is sent from.

assignUsers

string[]

assign_users: Only assign the users defined in the request payload
assign_owner: Assign the users defined in the request payload in addition to the owner's users.

claimRule

string · enum

If provided, sets the claim rule for a newly created conversation. The value is ignored if the conversation already exists.

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notificationMode

string · enum

Controls notification and unread indicators for API-delivered messages.

Defaults to notify_unread.

Values:

notify_unread: Sends a system notification and keeps the message unread. Use for messages that need immediate attention.
silent_unread: Suppresses system notifications and keeps the message unread. Use for bulk messages that users can check later.
silent_read: Suppresses system notifications and marks the message as read unless the conversation already has existing unread messages. Use for background delivery.

Enum values:

notify_unread

silent_read

silent_unread

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

routingAction

string · enum

Defines whether to assign users to the conversation that is created as a result of the message.

Possible values:

assign_users: Assign the conversation to one or more Spoke users. If this value is used, the assignUsers parameter must be non-empty
do_not_route: Do not assign any Spoke users to the conversation. If the customer replies, no one will be able to respond to the customer
assign_owner: Assign the conversation to the owner of the company address. Currently supports team and member owners only.

Enum values:

assign_owner

assign_users

do_not_route

Send a new conversation message › Responses

Successfully sent the message

CreateConversationMessageResponse

hasExistingConversation

boolean · required

vendor

string · enum · required

The CPaaS vendor that carried the message. One of the following values:

twilio

Enum values:

twilio

vendorConversationId

string · required

The vendor's identifier of the conversation associated with the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the ConversationSid of the conversation

vendorMessageId

string

The vendor's identifier of the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the MessageSid of the message

Send a new SMS message

POST

https://integration.spokephone.com

/messages

DEPRECATED: This endpoint has been deprecated and will be removed in a future version of the API. Please use the POST /conversationMessages endpoint instead.

Send a new SMS message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new SMS message › Request Body optional

CreateMessageBody

body

string · required

The content of the message, can be up to 1,600 characters long

from

string · required

Either the user’s email address, or their SMS enabled DDI (in +E164 form). If an email address is provided, we will automatically use the user’s default SMS DDI

to

string · required

The recipient’s phone number in +E164 form, e.g. +61488881234 or +155512345678

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notifyUsers

boolean

Controls whether notifications for this message are sent to users.

When a conversation already exists between the company address and the contact address, setting notifyUsers to false will still notify the existing participants.

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Send a new SMS message › Responses

Successfully sent the message

CreateMessageResponse

success

boolean · required

Send a new Team SMS message

POST

https://integration.spokephone.com

/teamMessages

DEPRECATED: This endpoint has been deprecated and will be removed in a future version of the API. Please use the POST /conversationMessages endpoint instead.

Send a new Team SMS message › Headers

Authorization

Authorization · required

Authorization header bearing the access token

Send a new Team SMS message › Request Body optional

anyOf

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

Decision Table

Variant	Matching Criteria
	type = object · requires: companyAddress, contactAddress, messageContent
	type = object · requires: channel, companyAddress, contactAddresses +1 more

Properties for CreateSmsTeamMessageBody:

CreateSmsTeamMessageBody

companyAddress

string · required

The company number to use as the sender Id. Must be in +E164 format.

contactAddress

string · required

The number of the contact to send the message to. Must be in +E164 format.

CreateMessageContent · required

assign_users: Only assign the users defined in the request payload
assign_team: Assign the users defined in the request payload in addition to the team’s users.

channel

string

The type of the conversation channel.

This field is optional and defaults to the sms channel if not provided. If provided, the value must be sms, signifying that the message is an SMS message to a single contact.

If provided, sets the claim rule for a newly created conversation. The value is ignored if the conversation already exists.

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)

conversationName

string

If provided, then use the provided value to set the initial Conversation Name. This value displays in the conversations list in the Spoke application. Can be up to 100 characters long.

notifyUsers

boolean

Controls whether notifications for this message are sent to users.

When a conversation already exists between the company address and the contact address(es), setting notifyUsers to false will still notify the existing participants.

object

If provided, stores passthrough parameters against the conversation. Passthrough parameters are included in the conversation's webhook events.

Use passthrough parameters to track conversations, ensuring the outcome of a conversation can be associated correctly with your external applications (such as CRM or in-house systems).

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

Example:


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

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Defines whether to assign users to the conversation that is created as a result of the message.

Send a new Team SMS message › Responses

Successfully sent the message

CreateTeamMessageResponse

hasExistingConversation

boolean · required

vendor

string · enum · required

The CPaaS vendor that carried the message. One of the following values:

twilio

Enum values:

twilio

vendorConversationId

string · required

The vendor's identifier of the conversation associated with the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the ConversationSid of the conversation

vendorMessageId

string

The vendor's identifier of the message that was created. The value of this field is dependent on the value of the vendor field:

twilio: the MessageSid of the message