API docs by Redocly

Switchboard API Documents (1.0.0)

Download OpenAPI specification:Download

Delta Force Developers: deltaforcedev@zillowgroup.com

See Gitlab Repo

See developer guide

What's Switchboard Conversations (SBC)?

Switchboard Conversations (SBC) is a backend messaging platform that clients can leverage for any messaging experience. The platform handles conversational storage as well as sending/receiving messages across various channels. Currently, the platform is focused on the SMS channel and the in-app channel, but the in-app channel spans multiple persona’s and clients, such as Alan’s in FUB (through STIP), Alan’s in PA App, Beth in ZG app, LO’s in Salesforce, Operators in Pearl (soon to come). SBC is also set up in a way to easily add channels to their platform.

Beyond the basic conversational functionality, SBC provides enhanced functionality that clients can leverage through their API’s. Things such as unread count, pagination, silent messages, and message statuses. SBC is ever evolving, however, as we seek to become a state of the art messaging system. Thus, we are always looking to improve and increase our features set. We work closely with clients to understand their top priorities and add those to our set of features that are available to all. You can see more below around current features and future features.

Why Switchboard Conversations?

Conversations are a foundational piece to every connection, transaction, and overall customer experience. Thus, as we continue to strive for the Zillow 2.0 vision, we need to continue to invest in our conversation capabilities for not only Beth, but for all our personas. Switchboard Conversations is here to help all engineering teams across Zillow build the best conversational experience possible and do it quicker than ever. From our platform you will be able to immediately leverage critical backend messaging capabilities, to build out your conversational experience faster and better than ever.

Get Started

Quickstart

In order to start using Switchboard Conversations effectively, clients must first complete the onboarding process. This requires registering their client details and callback configurations, allowing Switchboard to determine where to send notifications. Clients should follow these steps:

1. Registering as a client in SBC's UI

Clients are required to access Switchboard's UI and begin the registration process.

Environment SBC's User Interface
Production https://switchboard-admin-ui-prod.corp.connectionsplatform-prod-k8s.zg-int.net/client-management

2. Providing client information

After accesing the UI, clients must click on the "New Client" button and provide the following information:

  • Client Name: The client name should adhere to the naming convention, which follows the format of "consumer name - target service - environment name"
  • User
  • Zodiac team
  • Client Type
    • Internal
    • External
  • Primary Target
    • HTTP
    • SQS
    • Kafka
  • Backup target
    • HTTP
    • SQS
    • Kafka

3. Initiate integration

After details are registered, clients can start the integration process. The base URL for the API requests varies depending on the environment:

Environment URL
Production https://switchboard-api-gateway-prod.int.connectionsplatform-prod-k8s.zg-int.net
Staging https://switchboard-api-gateway-stage.int.connectionsplatform-nonprod-k8s.zg-int.net
Development https://switchboard-api-gateway-dev.int.connectionsplatform-nonprod-k8s.zg-int.net

When making requests to the API, ensure you include the following headers:

Key Value
Content-Type application/json

Typical conversation flow

  1. Check the existence of a conversation:
  • Clients should use the /GetConversations endpoint to check for an exact match with participant IDs. This will allow them to determine whether a conversation between the given participants already exists or if a new one should be created.
  1. Creating or Retrieving Conversations:
  • Clients can use the /CreateConversation endpoint to create a new conversation with the participants' IDs if a conversation doesn't exist.
  • If a conversation already exists, clients can use /GetConversationMessages to fetch the messages in a given conversation.
  1. Send Messages:
  • Clients can use the /SendMessage endpoint to send messages in a specified conversation. This endpoint also checks the validity of the sender, increments the unread count of other participants, and it publishes the message created event.

Migrating to Sync SMS

Migrating to SBC's new synchronous endpoint will significantly streamline client's experience and address several critical pain points, including:

  • Immediate Request Validation: Get instant feedback on request validity without waiting for async status callbacks.

  • Reduced Complexity: Eliminate the bugs and inefficiencies associated with syncing data between SBC, SMS, and Twilio.

  • Simplified Architecture: Manage conversations directly within SBC, removing dependencies on Twilio and reducing architectural complexity.

To migrate from async to sync endpoints, clients should make the following changes:

  1. Creating a Conversation: Migrate from /ReceiveConversationEvent to /CreateConversation to create 1-to-1 or group conversations.

  2. Sending a Message: Migrate from /ReceiveMessageEvent to /SendMessage to dispatch messages to specified conversations.

  3. Checking Delivery Status: Use /GetMessage to retrieve message details, including status, persona, metadata, and whether it is a silent message.

Key Definitions

The base URL for all API requests varies depending on the environment:

Concept Definition
Conversation Refers to the space where two or more participants can exchange messages.
Message Is a text exchanged between participants within a conversation.
Participant Refers to a specific user who is part of a conversation.
Bot Is a software program that interacts with other users in a conversation by sending automated messages.
Unread Count Is the number of messages a specific participant has not yet read in a conversation.
Persona Refers to the type of participant in a conversation. SBC supports the following persona types: UNSPECIFIED, CONSUMER, BUYER, SELLER, SYSTEM, CONCIERGEREP, SELLERAGENT, BUYERAGENT, LOANPROCESSOR, LOANOFFICER_ASSISTANT, LOANOFFICER_MANAGER, AGENT, ZG_AI_LLM_BOT, and ZILLOW.
Native System Refers to the unique client name for the participant's platform that was assigned when onboarded to SBC.

Conversations

APIs related to creating and fetching a conversation.

/CreateConversation

This endpoint allows clients to create either a one-to-one or group conversation. If an identical set of participants is already in an existing conversation, the endpoint will not create a new conversation and will instead return the existing one. This prevents duplicate conversations from being created with the same participants.

Request Body schema: application/json
client_name
required
string

client_name is the unique client name for the sender's platform that was assigned when onboarded to SBC.

required
Array of objects

participants represent the active participants in the conversation.

Array of objects

metadata is the metadata related to the conversation

version
required
string
Default: "V0"
Enum: "V0" "V1"

version is the workflow version. Clients should always use V1.

Responses

Request samples

Content type
application/json
{
  • "client_name": "mercury-in-app-messaging-dev",
  • "participants": [
    ],
  • "metadata": [
    ],
  • "version": "V1"
}

Response samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "create_dt": "2024-05-13T20:22:24.772122129Z"
}

/GetConversationDetails

The /GetConversationDetails endpoint is designed to be both fast and lightweight, enabling clients to retrieve the details of the participants, message metadata, and unread count, all without the need to fetch all the messages in the conversation.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id of the conversation.

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49"
}

Response samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "participants": [
    ],
  • "create_dt": "2024-05-13T08:09:24.136044709Z",
  • "metadata": [
    ]
}

/GetConversations

Returns the all conversations for a given participant reference. This includes the conversation's last read message and the unread count for that participant.

Request Body schema: application/json
object

is the participant's id and type

limit
integer [ 1 .. 10 ]

the number of conversations to be returned in each list page. The maximum is 10.

cursor
string

optional field which, when provided, returns the conversations following the cursor

Responses

Request samples

Content type
application/json
{
  • "participant": {
    },
  • "limit": 10,
  • "cursor": "MjAyNS0wNC0zMFQxNTowMzoyNS44ODYyMDYzMDZa"
}

Response samples

Content type
application/json
{
  • "conversations": [
    ],
  • "pagination": {
    }
}

/GetConversationsSummary

Retrieve all conversations in which a specific participant has taken part, and provide the count of unread messages for that user along with the associated conversation IDs.

Request Body schema: application/json
required
object

is the participant's id and type

Responses

Request samples

Content type
application/json
{
  • "participant": {
    }
}

Response samples

Content type
application/json
{
  • "conversations": [
    ]
}

/AddParticipants

This endpoint allows clients to add one or more participants to an existing conversation. Participants can be added with their reference, persona type, and optional channels.

Request Body schema: application/json
conversation_id
required
string

The UUID of the conversation

required
Array of objects non-empty

List of participants to add to the conversation

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "string",
  • "participants": [
    ]
}

Response samples

Content type
application/json
{ }

Messages

Below are the API's related to sending and fetching messages. We have a couple unique properties that you can apply to a message for unique functionality.

Optional Features of a Message

Feature Functionality How To
Silent Sending a message that does not add to the unread count nor appear in the recent message preview for the recipients of the message. Set isSilent = True on the message object when using /SendMessage.
Targeted Sending a message to a subset of participants in a conversation, instead of all the participants. Targeted messages will only notify the specified recipients of a new message. The message is still threaded in the conversation history. Thus, when retrieving messages, clients can add a filter to specify from which participant perspective they want to retrieve the messages. When sending a message indicate an array of recipients on the message object. When retrieving messages, specify a participant as a filter
Attachments SBC platform allows its in-App clients to upload and retrieve media Messages in a safe and secure way. SBC is responsible for securely storing messages via zDocs sent between users and efficiently retrieving them when needed. This ensures that clients have access to fetch user message history at all times. Clients can send up to 10 media attachments per message. The client is responsible for determining how messages are rendered in the chat interface. This includes deciding on the layout and style when messages contain various types of content, such as multiple images or a combination of images and text. The client (example: ZIM, FUB etc.) allows Beth/Alan to send and receive messages, manage their conversations, and engage with other features of the chat application Clients first must request an uploadURL via SBC in order to upload their content. SBC returns upload URL to the client. For every attachment uploaded, the client gets a token back which they pass in the attachments object in the SendMessage request.

Retrieve messages from a conversation

This endpoint supports pagination for retrieving the messages of a conversation.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id of the conversation.

cursor
string

cursor is provided by the API.

If the cursor is empty, then all the messages are returned starting with the latest message up until the limit is reached.

If the cursor is provided, then all the messages from a conversation starting at that corresponding message up until the limit will be returned.

limit
required
number [ 1 .. 250 ]

limit is the number of messages to be returned in each list page.

object

is the participant's id and type

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "cursor": 1780533361220997000,
  • "limit": 20,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "messages": [
    ],
  • "pagination": {
    }
}

Retrieve a message

Get a given message by its ID. Clients can use this to get the message details, including the status, persona, metadata and if it's a silent message. When clients make a request to SBC to retrieve their media message(s), SBC will make a request to zDocs to generate time-limited URLs which clients can use to render the media in the UI.

Request Body schema: application/json
message_id
required
string

message_id is the id of the message

Responses

Request samples

Content type
application/json
{
  • "message_id": "1789930931922931712"
}

Response samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "notification_connection_id": "6319582f-1887-11ef-b681-2678d607e699",
  • "message_id": "1789930931922931712",
  • "message": {
    }
}

Send a message

SendMessage allows a client to send a message to a specified conversation. The message can include text and metadata, and it will be processed and stored in the database.

The client can specify the origin of the message (e.g., HDP, SMS_reply, ZIM_inbox) and the platform (Web, Mobile, iOS, Android) using dedicated headers. These headers allow SBC to track where the message was sent from and the platform used. Idempotency can also be provisioned by including a dedicated z-idempotency-key header in the request. SBC will then stream this data into the Data Lake, making it available for data analytics purposes.

This endpoint also checks the validity of the sender, increments the unread count of other participants, and it publishes the message created event.

Media messaging

After requesting pre-signed URLs via SBC to use for upload, clients will call SendMessage with the corresponding uploadToken provided to them (by zDocs). SBC will then use that to lookup details about the file in zDocs & persist any necessary information in our data layer.
header Parameters
z-user-platform
string
Example: iOS

Indicates where the message was sent from (Web, Mobile, iOS, Android.)

z-message-origin
string
Example: HDP

Indicates source through which the sender's message arrives in SBC (e.g., HDP, SMS_reply, ZIM_inbox).

z-idempotency-key
string
Example: 93aae560-e4f6-11ef-a6d8-f2a8468e00ea

Indicates idempotency key for the message.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id of the conversation.

required
object

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "986b391a-0a5c-11ef-bc51-96e8f7b18a49",
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "message_id": 1789930931922931700,
  • "create_dt": "2024-05-13T08:09:24.136Z"
}

Get Upload URL

The client would call SBC’s /GetUploadURL endpoint with payload provided. Then SBC will do following:

Request Auth JWT token for the tenant which this conversation uses for saving data. Do an authenticated request to zDocs /api/v1/documents/actions/upload/request (spec) to retrieve a pre-signed url with a TTL of 24 hours SBC’s response to client will contain both the zDocs signedUrl and the expires_at time.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id of the conversation.

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "986b391a-0a5c-11ef-bc51-96e8f7b18a49"
}

Response samples

Content type
application/json
{}

Conversations v2

REST APIs related to creating and fetching conversations.

Get OAuth Token

Retrieves new OAuth Token

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Request Body schema: application/json
client_id
required
string non-empty

Zillow OAuth Client ID

client_secret
required
string non-empty

Zillow OAuth Client Secret

grant_type
required
string non-empty

Grant type, always 'client_credentials'

scopes
required
Array of strings

Array of requested scopes. 'sbc/conversations.write' is necessary.

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "grant_type": "string",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

List Conversations

Lists conversations for a participant or a group of participants.

Authorizations:
BearerAuth
query Parameters
participant
required
Array of strings non-empty

One or more participant ID in the format of type:userid

limit
integer <int32>

Limits the number of returned conversations when querying for a single participant. If omitted, all matching conversations are returned. Does not apply to querying for a group of participants.

cursor
string

A pagination marker from which to continue retrieving next limit number of conversations

exact_match
boolean

When set to true, multi-participant search for N participants may find exactly one conversation: the one involving all the participants and no one else. When set to false or omitted, returns the conversations which involve all the listed participants and may be some additional users - having N+ participants.

is_archived
boolean

Filter the conversations by is_archived status

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "conversations": [
    ],
  • "meta": {
    }
}

Create a Conversation

Creates a one-to-one or group conversation. The set of participants, identified by their userid and userid_type pairs, must be unique. If a conversation with the given set of participants already exists, a 409 error is returned.

Authorizations:
BearerAuth
header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Request Body schema: application/json
Array of objects

Some additional information about this conversation

required
Array of objects >= 2 items

Participants, at least two

Responses

Request samples

Content type
application/json
{
  • "metadata": [
    ],
  • "participants": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": [
    ],
  • "participants": [
    ],
  • "id": "string",
  • "is_archived": true,
  • "create_dt": "string",
  • "update_dt": "string"
}

Get a Conversation

Retrieves details about a conversation. Messages are not included.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "metadata": [
    ],
  • "participants": [
    ],
  • "id": "string",
  • "is_archived": true,
  • "create_dt": "string",
  • "update_dt": "string"
}

Update a Conversation

This endpoint allows users to update a subset of mutable fields (listed below). If a field is included it will be updated, otherwise it will be ignored. The conversation must exist, otherwise a 404 error is returned.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Request Body schema: application/json
is_archived
boolean

If true, the conversation will be marked as archived; if false, it will be unarchived. Archived conversations cannot send or receive new messages

Array of objects

A list of metadata objects to associate with the conversation. Each metadata entry can store additional information about the conversation.

Responses

Request samples

Content type
application/json
{
  • "is_archived": true,
  • "metadata": [
    ]
}

Response samples

Content type
application/json
{
  • "msg": "string",
  • "meta": { }
}

Add participants to a conversation

Adds one or more participants to an existing conversation. The conversation must exist, otherwise a 409 conflict is returned.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Request Body schema: application/json
required
Array of objects non-empty

Participants, at least one

Responses

Request samples

Content type
application/json
{
  • "participants": [
    ]
}

Response samples

Content type
application/json
{
  • "msg": "string",
  • "meta": { }
}

Create an Upload URL

Creates a signed, expiring upload URL for uploading media files.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "upload_url": "string",
  • "expires_at": "string"
}

Get User's Conversations Summary

Retrieves a summary of conversations for a user, including unread message counts. Can be filtered by allowed channel types.

Authorizations:
BearerAuth
path Parameters
userID
required
string
Examples: phone:+14158887722

User ID for which the conversation summary is requested

query Parameters
conversation_channel_type
Array of strings

List only those conversations where ALL participants use that channel type

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "conversations": [
    ]
}

Messages v2

REST APIs related to sending and fetching messages

Get Message details

Get all the details of the message. Given a conversation ID and a message ID, this endpoint will fetch the relevant attributes of the requested message. If the message is not found, then a 404 error is returned.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...
required
string or string
header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "attachments": [
    ],
  • "metadata": [
    ],
  • "recipients": [
    ],
  • "sender": {
    },
  • "id": "string",
  • "body": "string",
  • "is_silent": true,
  • "create_dt": "string",
  • "update_dt": "string"
}

Fetch all the messages for a given conversation

Given a conversation ID and a limit, fetches the limit number of the messages for that conversation. If the conversation does not exist, then a 404 error is returned.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

query Parameters
participant
Array of strings

Optional query parameter to allow filtering by participants. It accepts an array of participant ids of the form {type:ID}

limit
integer <int32> [ 1 .. 250 ]

Optional query parameter to return the provided limit number of messages. Should be in the range of [1, 250]. Defaults to 20 messages if the parameter is not provided.

before
string

Optional query parameter for cursor-based pagination. Returns messages that were created before (older than) the specified cursor. Cannot be used together with the 'after' parameter.

after
string

Optional query parameter for cursor-based pagination. Returns messages that were created after (newer than) the specified cursor. Cannot be used together with the 'before' parameter.

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "meta": {
    }
}

Send a Message

Given a Conversation ID, adds a message to the conversation.

Clients can specify the origin of the message (e.g., HDP, SMS_reply, ZIM_inbox) and the platform (Web, Mobile, iOS, Android) using dedicated headers. These headers allow SBC to track where the message was sent from and the platform used.

Idempotency is also supported by including a dedicated z-idempotency-key header in the request.

The endpoint increments the unread count of other participants and kicks off the async process for message delivery.

The message can include text, metadata or attachments (files, images). The endpoint checks that Sender is a participant in the conversation. Supports targeted messages by specifying a set of recipients (subset of participants). Otherwise message will be delivered to all the participants in the conversation. Supports silent messages (via is_silent field) which means the message will not be counted towards unread count and is also not shown in the latest message view.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

z-user-platform
string

Indicates where the message was sent from - Web, Mobile, iOS, Android.

z-message-origin
string

Indicates source through which the sender's message arrives in SBC. e.g., HDP, SMS_reply, ZIM_inbox.

z-idempotency-key
string

Indicates idempotency key for the message. Rejects duplicate requests with the same key

Request Body schema: application/json
body
required
string

The plain text content of the message

is_silent
boolean

When true, the message will not count towards unread count and also doesn't show up in the latest message view. Default value is false.

required
object

Reference to the user sending the message

Array of objects

If empty or omitted, message will be delivered to all the participants Otherwise, message will be delivered to specified recipients

Array of objects

Additional metadata associated with the message

Array of objects

Files or other content attached to the message

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "is_silent": true,
  • "sender": {
    },
  • "recipients": [
    ],
  • "metadata": [
    ],
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "attachments": [
    ],
  • "metadata": [
    ],
  • "recipients": [
    ],
  • "sender": {
    },
  • "id": "string",
  • "body": "string",
  • "is_silent": true,
  • "create_dt": "string",
  • "update_dt": "string"
}

Update a Recipient's Message Status

Updates the delivery status of a given recipient. This endpoint allows users to update the delivery status and/or failure reason for a message's recipient. If the status is FAILED, failure reason may be provided.

Authorizations:
BearerAuth
path Parameters
convID
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Conversation UUID

required
string or string

Message ID

userID
required
string
Examples: phone:+14158887722

Participant details in the format of type:userid

header Parameters
z-client-id
required
string non-empty

The name of the service which is making the request

Request Body schema: application/json
delivery_status
required
string
Enum: "UNDEFINED" "PENDING" "FANOUT" "SENT" "DELIVERED" "CLIENT_RECEIVED" "READ" "FAILED" "UNDELIVERED" "NOT_APPLICABLE"

The delivery status of the message for the recipient.

delivery_failure_reason
string

The optional failure reason for cases where the delivery status is FAILED.

Responses

Request samples

Content type
application/json
{
  • "delivery_status": "UNDEFINED",
  • "delivery_failure_reason": "string"
}

Response samples

Content type
application/json
{
  • "msg": "string",
  • "meta": { }
}

Message Status

Message Status gives clients the ability to track the delivery status of each message through the SBC platform. These statuses are updated in real time and reflect the current state of delivery from the platform's perspective.

The diagram below illustrates the various statuses a message can have throughout the conversation flow.

Supported Message Statuses

Status Definition
UNDEFINED The default value.
PENDING The message has been created and is in the queue, waiting to be processed. This status indicates that the message has not yet been sent and is still in the intial stages of delivery.
FANOUT The message is being processed by SBC Delivery System.
SENT The message has been successfully sent to the recipient's messaging service or network. This status confirms that the message has been handed off by SBC but does not yet guarantee that it has been received by the recipient.
DELIVERED The message has been successfully delivered to the recipient's application. This status confirms that the message is now available for the recipient to view. It indicates successful transmission of a message from SBC to the messaging service; however, it does not guarantee that the receipient received the message on their native device.
CLIENT_RECEIVED This status indicates that the recipient has received a notification of the message on their device. NOTE: Not all client systems support this status.
READ This status indicates that the recipient has opened and viewed the message. It confirms that the message has not only been delivered but also seen by the recipient, providing an additional level of confirmation beyond delivery.
FAILED The message could not be sent or delivered by SBC due to an error. This status indicates that an issue occurred during the delivery process for SBC, and the message was not successfully sent or received.
UNDELIVERED The client could not deliver the message to the recipient.
NOT_APPLICABLE The message isn't meant to be delivered to this recipient by SBC. Usually happens for inbound SMS messages in SMS group conversation. Such messages are delivered to other SMS recipients by the messaging service, not SBC.

Update recipient message status

SBC allows for updating the message status on a per-participant basis, enabling the capture of individual recipient engagement. When a message status is updated for a recipient, it will also impact that user's unread message count. Specifically, marking a message as read will reset the user's last read message to the one indicated in the request payload, ensuring accurate tracking of message engagement and unread messages.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id for the conversation.

message_id
required
any

message_id is the ID of the message

required
object

is the participant's id and type

status
required
string
Enum: "PENDING" "SENT" "DELIVERED" "CLIENT_RECEIVED" "READ" "FAILED" "UNDELIVERED"

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "829feab5-1166-11ef-a6af-16e4c685cd49",
  • "message_id": "1789930931922931712",
  • "recipient": {
    },
  • "status": "SENT"
}

Response samples

Content type
application/json
{ }

Post Hooks

Post hooks are HTTP callbacks that Switchboard sends to your application when specific events occur within the platform. These webhooks allow your system to react in real-time to events such as message delivery, conversation updates, and status changes.

How Post Hooks Work

  1. Event Occurs: When an event happens in Switchboard (e.g., message sent, conversation created), the system triggers a post hook.
  2. HTTP Request: Switchboard sends an HTTP POST request to your configured endpoint with event data. The target must be specified as part of the initial client registration in the Switchboard Client.
  3. Your Response: Your application processes the event and responds with an HTTP status code.
  4. Retry Logic: If your endpoint doesn't respond successfully, Switchboard will retry the request according to configured retry policies.

Supported Events

Event Type Description Trigger
message.created Triggered when a message is successfully sent After message passes through SBC delivery system
message.updated Triggered when a message is updated When message is updated
conversation.created Triggered when a new conversation is created After successful conversation creation
conversation.updated Triggered when conversation details are modified When conversation is archived or metadata changes
participant.created Triggered when participants are added to conversation After successful participant addition

Post Hook Payload Structure

All post hooks follow a consistent payload structure based on the PostHookRequest schema. Any changes to the schema will be backwards compatible. Each webhook contains:

  • event_id: Unique identifier for the webhook event
  • event_dt: ISO 8601 timestamp when the system created the event
  • event_type: The type of post-hook event (message.created, message.updated, conversation.created, etc.)
  • context: Contextual data including conversation information
  • before: Previous state of the resource (empty for creation events)
  • after: Updated state of the resource after the event

For complete schema definitions, see the PostHookRequest and related schemas in the components section.

Post Hook Webhook Payload Webhook

This documents the webhook payload structure that Switchboard sends to your registered webhook URL.

When events occur in Switchboard (message creation, conversation updates, etc.), the system will send HTTP POST requests to your configured webhook endpoint with this payload structure.

Webhook Configuration:

  • Configure your webhook URL during client registration in the Switchboard Admin UI
  • Your endpoint must accept HTTP POST requests
  • Your endpoint should respond with a 2xx status code to acknowledge receipt
  • Failed webhooks will be retried according to the configured retry policy

Event Types:

  • message.created - Triggered when a message is successfully sent
  • message.updated - Triggered when a message is updated
  • conversation.created - Triggered when a new conversation is created
  • conversation.updated - Triggered when conversation details are modified
  • participant.created - Triggered when participants are added to a conversation
  • participant.updated - Triggered when participant details are modified

Payload Structure: All webhooks follow the consistent PostHookRequest schema structure shown below.

Request Body schema: application/json

The webhook payload sent by Switchboard to your configured endpoint

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
Example

Example webhook payload when a new message is created

{
  • "event_id": "550e8400-e29b-41d4-a716-446655440000",
  • "event_dt": "2024-05-13T08:09:24.136Z",
  • "event_type": "message.created",
  • "context": {
    },
  • "before": { },
  • "after": {
    }
}

Message Created Event Webhook

This webhook is triggered after a message passes through the SBC delivery system and is successfully sent to recipients.

Request Body schema: application/json

Payload

Information about the message that was created

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440000",
  • "event_dt": "2024-05-13T08:09:24.136Z",
  • "event_type": "message.created",
  • "context": {
    },
  • "before": { },
  • "after": {
    }
}

Message Updated Event Webhook

This webhook is triggered when a message is updated, such as when the delivery status changes for recipients.

Request Body schema: application/json

Payload

Information about the message that was updated

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440003",
  • "event_dt": "2024-05-13T08:10:15.247Z",
  • "event_type": "message.updated",
  • "context": {
    },
  • "before": {
    },
  • "after": {
    }
}

Conversation Created Event Webhook

This webhook is triggered after a conversation is successfully created with participants.

Request Body schema: application/json

Payload

Information about the conversation that was created

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440001",
  • "event_dt": "2024-05-13T08:09:24.136Z",
  • "event_type": "conversation.created",
  • "context": { },
  • "before": { },
  • "after": {
    }
}

Conversation Updated Event Webhook

This webhook is triggered when conversation details are modified, such as when a conversation is archived or metadata changes.

Request Body schema: application/json

Payload

Information about the conversation that was updated

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
Example
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440004",
  • "event_dt": "2024-05-13T08:15:30.542Z",
  • "event_type": "conversation.updated",
  • "context": { },
  • "before": {
    },
  • "after": {
    }
}

Participant Created Event Webhook

This webhook is triggered after participants are successfully added to an existing conversation.

Request Body schema: application/json

Payload

Information about the participant that was added

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440002",
  • "event_dt": "2024-05-13T08:09:24.136Z",
  • "event_type": "participant.created",
  • "context": {
    },
  • "before": { },
  • "after": {
    }
}

Participant Updated Event Webhook

This webhook is triggered when a participant is updated in a conversation, such as when participant metadata or channel information changes.

Request Body schema: application/json

Payload

Information about the participant that was updated

event_id
required
string non-empty

Unique identifier for the webhook event

event_dt
required
string

The timestamp (ISO 8601 format) indicating when the system created the event

event_type
required
string
Enum: "message.created" "message.updated" "conversation.created" "conversation.updated" "participant.created" "participant.updated"

The type of post-hook event that occurred

required
object

Structured contextual data included with the event, such as the associated conversation, message, participants, etc

required
object

Previous state of the resource (empty object for creation events)

required
object

The updated state of the resource after the event

Responses

Request samples

Content type
application/json
{
  • "event_id": "550e8400-e29b-41d4-a716-446655440007",
  • "event_dt": "2024-05-13T08:30:42.123Z",
  • "event_type": "participant.updated",
  • "context": {
    },
  • "before": {
    },
  • "after": {
    }
}

Notifications

Below are the API's related to sending notifications.

Send a notification

Allows a client to send a notification to a recipient on a specific channel.

Request Body schema: application/json
conversation_id
required
string

conversation_id is the unique id of the conversation.

message_id
string

message_id is the unique id of the message generated by SBC.

required
object

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "986b391a-0a5c-11ef-bc51-96e8f7b18a49",
  • "message_id": "1789930931922931712",
  • "notification": {
    }
}

Response samples

Content type
application/json
{ }