HighLevel: Conversations schemas

← Conversations operations · All schemas

Add an external outbound call — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
altId	string	Optional	external mail provider's message id
attachments	array	Optional	Array of attachments
attachments[]	string	Each item
call	JSON	Optional	Phone call dialer and receiver information
call (allOf 1)	Model	All variants apply	Expand Add an inbound message — request body — body call from, status, to
conversationId	string	Required within parent	Conversation Id
conversationProviderId	string	Required within parent	Conversation Provider Id
date	string	Optional	Date of the outbound message Format: date-time
type	string	Required within parent	Message Type One of: Call

Referenced models: Add an inbound message — request body — body call from, status, to

Add an inbound message — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
altId	string	Optional	external mail provider's message id
attachments	array	Optional	Array of attachments
attachments[]	string	Each item
call	JSON	Optional	Phone call dialer and receiver information
call (allOf 1)	Model	All variants apply	Expand Add an inbound message — request body — body call from, status, to
contactId	string	Required within parent	Contact Id
conversationId	string	Required within parent	Conversation Id
conversationProviderId	string	Required within parent	Conversation Provider Id
date	string	Optional	Date of the inbound message Format: date-time
direction	object	Optional	Message direction, if required can be set manually, default is outbound Default: outbound
emailBcc	array	Optional	List of email address to BCC
emailBcc[]	string	Each item
emailCc	array	Optional	List of email address to CC
emailCc[]	string	Each item
emailFrom	string	Optional	Email address to send from. This field is associated with the contact record and cannot be dynamically changed.
emailMessageId	string	Optional	Send the email message id for which this email should be threaded. This is for replying to a specific email
emailTo	string	Optional	Recipient email address. This field is associated with the contact record and cannot be dynamically changed.
html	string	Optional	HTML Body of Email
message	string	Optional	Message Body
subject	string	Optional	Subject of the Email
type	string	Required within parent	Message Type One of: SMS, RCS, Email, WhatsApp, GMB, IG, FB, Custom, WebChat, Live_Chat, Call, IVR_Call, Campaign_Call, Campaign_VoiceMail, TIKTOK, ALL_IN_ONE_CHAT, FORM_SUBMISSION

Referenced models: Add an inbound message — request body — body call from, status, to

Add an inbound message — request body — body call from, status, to

Field	Type	Presence	Description and constraints
$	object	Root
from	string	Optional	Phone number of the dialer
status	string	Optional	Call status One of: pending, completed, answered, busy, no-answer, failed, canceled, voicemail
to	string	Optional	Phone number of the receiver

Add an inbound message — response body

Field	Type	Presence	Description and constraints
$	object	Root
contactId	string	Optional	Contact ID associated with the processed message
conversationId	string	Required within parent	Conversation ID.
dateAdded	string	Optional	Timestamp when the processed message was created Format: date-time
emailMessageId	string	Optional	Email message ID created for email conversations
message	string	Required within parent	Result message returned after processing
messageId	string	Required within parent	This is the main Message ID
success	boolean	Required within parent	Whether the message processing succeeded

Add message attachments — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
attachments	array	Required within parent	Array of attachment URLs to set on the message (replaces existing). Maximum 5 URLs.
attachments[]	string	Each item

Agent Ai-Bot is typing a message indicator for live chat — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
conversationId	string	Required within parent	Conversation Id
isTyping	string	Required within parent	Typing status
locationId	string	Required within parent	Location Id
visitorId	string	Required within parent	Unique ID assigned to each live chat visitor.

Agent Ai-Bot is typing a message indicator for live chat — response body

Field	Type	Presence	Description and constraints
$	object	Root
success	boolean	Required within parent	Whether the live chat feedback was recorded successfully

Cancel a scheduled message — response body

Field	Type	Presence	Description and constraints
$	object	Root
message	string	Required within parent	Error message of the request
status	JSON	Required within parent
status (anyOf 1)	number	Alternative	HTTP Status code of the request
status (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Create Conversation — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
contactId	string	Required within parent	Contact ID as string
locationId	string	Required within parent	Location ID as string

Create Conversation — response body

Field	Type	Presence	Description and constraints
$	object	Root
conversation	JSON	Required within parent	Conversation data of the provided conversation ID.
conversation (allOf 1)	Model	All variants apply	Expand Create Conversation — response body — conversation assigned To, contact Id, date Added, date Updated, deleted, id, last Message Date, location Id
success	boolean	Required within parent	Indicates whether the API request was successful.

Referenced models: Create Conversation — response body — conversation assigned To, contact Id, date Added, date Updated, deleted, id, last Message Date, location Id

Create Conversation — response body — conversation assigned To, contact Id, date Added, date Updated, deleted, id, last Message Date, location Id

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Unique identifier of the team member assigned to this conversation
contactId	string	Required within parent	Unique identifier of the contact associated with this conversation
dateAdded	string	Required within parent	Date when the conversation was created
dateUpdated	string	Required within parent	Date when the conversation was last updated
deleted	boolean	Required within parent	Flag indicating if this conversation has been deleted
id	string	Required within parent	Unique identifier for the conversation
lastMessageDate	string	Required within parent	Date of the last message in the conversation
locationId	string	Required within parent	Unique identifier of the business location where this conversation takes place

Delete Conversation — response body

Field	Type	Presence	Description and constraints
$	object	Root
success	boolean	Required within parent	Boolean value as the API response.

Export messages by location ID — response body

Field	Type	Presence	Description and constraints
$	object	Root
messages	array	Required within parent	Array of messages
messages[]	Model	Each item	Expand Get message by message id — response body
nextCursor	string	Optional	Cursor for fetching next page. Null if no more results.
total	JSON	Required within parent
total (anyOf 1)	number	Alternative	Total number of messages matching the query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Get message by message id — response body

Get Conversation — response body

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Unique identifier of the team member currently responsible for handling this conversation
contactId	string	Required within parent	Unique identifier of the contact associated with this conversation
deleted	boolean	Required within parent	Flag indicating if this conversation has been moved to trash/deleted
id	string	Required within parent	Unique identifier for this specific conversation thread
inbox	boolean	Required within parent	Flag indicating if this conversation is currently in the main inbox view
locationId	string	Required within parent	Unique identifier of the business location where this conversation takes place
starred	boolean	Optional	Flag indicating if this conversation has been marked as important/starred by the user
type	JSON	Required within parent
type (anyOf 1)	number	Alternative	Communication channel type for this conversation: 1 (Phone), 2 (Email), 3 (Facebook Messenger), 4 (Review), 5 (Group SMS), 6 (Internal Chat - coming soon)
type (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
unreadCount	JSON	Required within parent
unreadCount (anyOf 1)	number	Alternative	Number of messages in this conversation that have not been read by the user
unreadCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Get email by Id — response body

Field	Type	Presence	Description and constraints
$	object	Root
altId	string	Optional	External Id
attachments	array	Optional	An array of attachment URLs.
attachments[]	string	Each item
bcc	array	Optional	List of email Ids of the people in the bcc field
bcc[]	string	Each item
body	string	Required within parent	Body content of the email message
cc	array	Optional	List of email Ids of the people in the cc field
cc[]	string	Each item
contactId	string	Required within parent	Contact ID associated with the email message
contentType	string	Required within parent	Content type of the email body
conversationId	string	Required within parent	Conversation ID associated with the email message
conversationProviderId	string	Optional	Conversation provider ID
dateAdded	string	Required within parent	Timestamp when the email message was created
direction	string	Required within parent	Direction of the email message Known values: inbound, outbound
from	string	Required within parent	Name and Email Id of the sender
id	string	Required within parent	Unique identifier for the email message
locationId	string	Required within parent	Location ID associated with the email message
provider	string	Optional	Email provider used to send or receive the message
replyToMessageId	string	Optional	In case of reply, email message Id of the reply to email
source	string	Optional	Email source Known values: workflow, bulk_actions, campaign, api, app
status	string	Optional	Delivery status of the email message Known values: pending, scheduled, sent, delivered, read, undelivered, connected, failed, opened
subject	string	Optional	Subject line of the email message
threadId	string	Required within parent	Message Id or thread Id
to	array	Required within parent	List of email Ids of the receivers
to[]	string	Each item

Get message by message id — response body

Field	Type	Presence	Description and constraints
$	object	Root
attachments	array	Optional	An array of attachment URLs. Attachments will be empty for Call and Voicemails, type 1 and 10. Please use get call recording API to fetch call recording and voicemails.
attachments[]	string	Each item
body	string	Optional	Body content of the message
chatWidgetId	string	Optional	Chat Widget Id
contactId	string	Required within parent	Contact ID associated with the message
contentType	string	Required within parent	Content type of the message body
conversationId	string	Required within parent	Conversation ID associated with the message
conversationProviderId	string	Optional	Conversation Provider Id
dateAdded	string	Required within parent	Timestamp when the message was created
direction	string	Required within parent	Direction of the message Known values: inbound, outbound
id	string	Required within parent	Unique identifier for the message
locationId	string	Required within parent	Location ID associated with the message
messageType	string	Required within parent	Type of the message as a string Known values: TYPE_CALL, TYPE_SMS, TYPE_RCS, TYPE_EMAIL, TYPE_SMS_REVIEW_REQUEST, TYPE_WEBCHAT, TYPE_SMS_NO_SHOW_REQUEST, TYPE_CAMPAIGN_SMS, TYPE_CAMPAIGN_CALL, TYPE_CAMPAIGN_EMAIL, TYPE_CAMPAIGN_VOICEMAIL, TYPE_FACEBOOK, TYPE_CAMPAIGN_FACEBOOK, TYPE_CAMPAIGN_MANUAL_CALL, TYPE_CAMPAIGN_MANUAL_SMS, TYPE_GMB, TYPE_CAMPAIGN_GMB, TYPE_REVIEW, TYPE_INSTAGRAM, TYPE_WHATSAPP, TYPE_CUSTOM_SMS, TYPE_CUSTOM_EMAIL, TYPE_CUSTOM_PROVIDER_SMS, TYPE_CUSTOM_PROVIDER_EMAIL, TYPE_IVR_CALL, TYPE_ACTIVITY_CONTACT, TYPE_ACTIVITY_INVOICE, TYPE_ACTIVITY_PAYMENT, TYPE_ACTIVITY_OPPORTUNITY, TYPE_LIVE_CHAT, TYPE_LIVE_CHAT_INFO_MESSAGE, TYPE_ACTIVITY_APPOINTMENT, TYPE_FACEBOOK_COMMENT, TYPE_INSTAGRAM_COMMENT, TYPE_CUSTOM_CALL, TYPE_INTERNAL_COMMENT, TYPE_ACTIVITY_EMPLOYEE_ACTION_LOG, TYPE_TIKTOK, TYPE_TIKTOK_COMMENT, TYPE_ACTIVITY_WHATSAPP, TYPE_FORM_SUBMISSION, TYPE_SMS_REACTION
meta	Model	Optional	Expand Get message by message id — response body — meta Additional metadata associated with the message
source	string	Optional	Message source Known values: workflow, bulk_actions, campaign, api, app
status	string	Optional	Delivery status of the message Known values: connected, delivered, failed, opened, pending, read, scheduled, sent, undelivered, clicked, opt_out, queued
type	JSON	Required within parent
type (anyOf 1)	number	Alternative	Numeric message type code
type (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
userId	string	Optional	User Id

Referenced models: Get message by message id — response body — meta

Get message by message id — response body — meta

Field	Type	Presence	Description and constraints
$	object	Root
callDuration	string	Optional	Call duration in seconds
callStatus	string	Optional	Call status - can be pending, completed, answered, busy, no-answer, failed, canceled, or voicemail Known values: pending, completed, answered, busy, no-answer, failed, canceled, voicemail
email	object	Optional	meta will contain email, for message type 3 (email). messageIds is list of all email message ids under the message thread

Get messages by conversation id — response body

Field	Type	Presence	Description and constraints
$	object	Root
lastMessageId	string	Required within parent	Id of the last message in the messages array
messages	array	Required within parent	Array of messages
messages[]	Model	Each item	Expand Get message by message id — response body
nextPage	boolean	Required within parent	Next page value true indicates only 20 message is in the response. Rest of the messages are in the next page. Please use the lastMessageId value in the query to get the next page messages

Referenced models: Get message by message id — response body

Get transcription by Message ID — response body

Field	Type	Presence	Description and constraints
$	object	Root
confidence	JSON	Required within parent
confidence (anyOf 1)	number	Alternative	Confidence of the transcription
confidence (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
endTime	JSON	Required within parent
endTime (anyOf 1)	number	Alternative	End time of the sentence in milliseconds
endTime (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
mediaChannel	JSON	Required within parent
mediaChannel (anyOf 1)	number	Alternative	Media channel describes the user interaction channel
mediaChannel (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
sentenceIndex	JSON	Required within parent
sentenceIndex (anyOf 1)	number	Alternative	Index of the sentence in the transcription
sentenceIndex (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startTime	JSON	Required within parent
startTime (anyOf 1)	number	Alternative	Start time of the sentence in milliseconds
startTime (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
transcript	string	Required within parent	Transcript of the sentence

Search Conversations — response body

Field	Type	Presence	Description and constraints
$	object	Root
conversations	array	Required within parent	The list of all conversations found for the given query
conversations[]	Model	Each item	Expand Search Conversations — response body — conversations item
total	JSON	Required within parent
total (anyOf 1)	number	Alternative	Total Number of results found for the given query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Search Conversations — response body — conversations item

Search Conversations — response body — conversations item

Field	Type	Presence	Description and constraints
$	object	Root
contactId	string	Required within parent	Contact Id
contactName	string	Required within parent	Alternative display name for the contact - used when full name is not available
email	string	Required within parent	Primary email address of the contact
fullName	string	Required within parent	Complete name of the contact (first and last name)
id	string	Required within parent	Conversation Id
lastMessageBody	string	Required within parent	Content of the most recent message in the conversation
lastMessageType	string	Required within parent	Channel/type of the most recent message (SMS, Email, Call, etc) Known values: TYPE_CALL, TYPE_SMS, TYPE_RCS, TYPE_EMAIL, TYPE_SMS_REVIEW_REQUEST, TYPE_WEBCHAT, TYPE_SMS_NO_SHOW_REQUEST, TYPE_CAMPAIGN_SMS, TYPE_CAMPAIGN_CALL, TYPE_CAMPAIGN_EMAIL, TYPE_CAMPAIGN_VOICEMAIL, TYPE_FACEBOOK, TYPE_CAMPAIGN_FACEBOOK, TYPE_CAMPAIGN_MANUAL_CALL, TYPE_CAMPAIGN_MANUAL_SMS, TYPE_GMB, TYPE_CAMPAIGN_GMB, TYPE_REVIEW, TYPE_INSTAGRAM, TYPE_WHATSAPP, TYPE_CUSTOM_SMS, TYPE_CUSTOM_EMAIL, TYPE_CUSTOM_PROVIDER_SMS, TYPE_CUSTOM_PROVIDER_EMAIL, TYPE_IVR_CALL, TYPE_ACTIVITY_CONTACT, TYPE_ACTIVITY_INVOICE, TYPE_ACTIVITY_PAYMENT, TYPE_ACTIVITY_OPPORTUNITY, TYPE_LIVE_CHAT, TYPE_LIVE_CHAT_INFO_MESSAGE, TYPE_ACTIVITY_APPOINTMENT, TYPE_FACEBOOK_COMMENT, TYPE_INSTAGRAM_COMMENT, TYPE_CUSTOM_CALL, TYPE_INTERNAL_COMMENT, TYPE_ACTIVITY_EMPLOYEE_ACTION_LOG, TYPE_TIKTOK, TYPE_TIKTOK_COMMENT, TYPE_ACTIVITY_WHATSAPP, TYPE_FORM_SUBMISSION, TYPE_SMS_REACTION
locationId	string	Required within parent	Location Id
phone	string	Required within parent	Primary phone number of the contact
type	string	Required within parent	Primary channel/type of the conversation (Phone, Email, etc) Known values: TYPE_PHONE, TYPE_EMAIL, TYPE_FB_MESSENGER, TYPE_REVIEW, TYPE_GROUP_SMS
unreadCount	JSON	Required within parent
unreadCount (anyOf 1)	number	Alternative	Number of unread messages in this conversation
unreadCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Send a new message — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
appointmentId	string	Optional	ID of the associated appointment
attachments	array	Optional	Array of attachment URLs
attachments[]	string	Each item
contactId	string	Required within parent	ID of the contact receiving the message
conversationProviderId	string	Optional	ID of conversation provider
customSubtypeId	string	Optional	Custom subtype ID for email unsubscription preferences. Only applies to email messages.
emailBcc	array	Optional	Array of BCC email addresses
emailBcc[]	string	Each item
emailCc	array	Optional	Array of CC email addresses
emailCc[]	string	Each item
emailFrom	string	Optional	Email address to send from
emailReplyMode	string	Optional	Mode for email replies One of: reply, reply_all
emailTo	string	Optional	Email address to send to, if different from contact's primary email. This should be a valid email address associated with the contact.
forward	JSON	Optional	Forwarding configuration for emails
forward (allOf 1)	Model	All variants apply	Expand Send a new message — request body — body forward email Message Id, forward Whole Thread, is Forwarded, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id, to Email
fromNumber	string	Optional	Phone number used as the sender number for outbound messages
html	string	Optional	HTML content of the message
message	string	Optional	Text content of the message
optimizationPeriod	string	Optional	Optimization period in hours (24h, 48h, or 72h) One of: 24h, 48h, 72h
replyMessageId	string	Optional	ID of message being replied to
scheduledTimestamp	number	Optional	UTC Timestamp (in seconds) at which the message should be scheduled
status	string	Required within parent	Message status One of: delivered, failed, pending, read
subType	object	Required within parent	Type of message being sent
subject	string	Optional	Subject line for email messages
templateId	string	Optional	ID of message template
threadId	string	Optional	ID of message thread. For email messages, this is the message ID that contains multiple email messages in the thread
toNumber	string	Optional	Recipient phone number for outbound messages
type	string	Required within parent	Type of message being sent One of: SMS, RCS, Email, WhatsApp, IG, FB, Custom, Live_Chat, TIKTOK
usesNativeSchedulingAi	boolean	Optional	Whether the scheduled email uses native AI for the email scheduling

Referenced models: Send a new message — request body — body forward email Message Id, forward Whole Thread, is Forwarded, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id, to Email

Send a new message — request body — body forward email Message Id, forward Whole Thread, is Forwarded, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id, to Email

Field	Type	Presence	Description and constraints
$	object	Root
emailMessageId	string	Optional	Email Message ID of the specific email being forwarded (source) - Required for single email forward, ignored for thread forward
forwardWholeThread	boolean	Optional	Specify if forwarding the whole thread or just a single email
isForwarded	boolean	Required within parent	Specify if this is a forwarded email
messageId	string	Optional	Message ID of the email thread being forwarded (source) - REQUIRED for forwarding
recipientContactId	string	Optional	Contact ID of recipient when forwarding (destination)
recipientConversationId	string	Optional	Conversation ID of recipient when forwarding (destination)
sourceContactId	string	Optional	Contact ID where the forwarded email originated from (source) - Auto-populated if not provided
sourceConversationId	string	Optional	Conversation ID where the forwarded email originated from (source) - Auto-populated if not provided
toEmail	string	Optional	Email address to forward to (destination)

Send a new message — response body

Field	Type	Presence	Description and constraints
$	object	Root
conversationId	string	Required within parent	Conversation ID.
emailMessageId	string	Optional	This contains the email message ID (only for Email type). Use this ID to send inbound replies through this API to create a threaded email.
forwardData	JSON	Optional	Optional metadata for forwarded email
forwardData (allOf 1)	Model	All variants apply	Expand Send a new message — response body — forward Data email Message Id, forward To Email, forward Whole Thread, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id
messageId	string	Required within parent	This is the main Message ID
messageIds	array	Optional	When sending via the GMB channel, we will be returning list of `messageIds` instead of single `messageId`.
messageIds[]	string	Each item
msg	string	Optional	Additional response message when sending a workflow message
status	string	Required within parent	Message status Known values: delivered, failed, pending, read

Referenced models: Send a new message — response body — forward Data email Message Id, forward To Email, forward Whole Thread, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id

Send a new message — response body — forward Data email Message Id, forward To Email, forward Whole Thread, message Id, recipient Contact Id, recipient Conversation Id, source Contact Id, source Conversation Id

Field	Type	Presence	Description and constraints
$	object	Root
emailMessageId	string	Optional	Email Message ID of the forwarded email (source)
forwardToEmail	string	Optional	Email address the message was forwarded to (destination)
forwardWholeThread	boolean	Optional	Whether the entire thread was forwarded
messageId	string	Optional	Message ID of the forwarded message (source)
recipientContactId	string	Optional	Contact ID of the recipient of the forwarded email (destination)
recipientConversationId	string	Optional	Conversation ID of the recipient of the forwarded email (destination)
sourceContactId	string	Optional	Contact ID where the forwarded email originated from (source)
sourceConversationId	string	Optional	Conversation ID where the forwarded email originated from (source)

Update Conversation — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
feedback	string	Optional	Live chat feedback value for the conversation One of: positive, negative
locationId	string	Required within parent	Location ID as string
starred	boolean	Optional	Starred status of the conversation.
unreadCount	number	Optional	Count of unread messages in the conversation

Update Conversation — response body

Field	Type	Presence	Description and constraints
$	object	Root
conversation	JSON	Required within parent	Conversation data of the provided conversation ID.
conversation (allOf 1)	Model	All variants apply	Expand Update Conversation — response body — conversation assigned To, contact Id, deleted, id, inbox, last Message Body, last Message Date, last Message Type, location Id, starred, unread Count, user Id
success	boolean	Required within parent	Boolean value as the API response.

Referenced models: Update Conversation — response body — conversation assigned To, contact Id, deleted, id, inbox, last Message Body, last Message Date, last Message Type, location Id, starred, unread Count, user Id

Update Conversation — response body — conversation assigned To, contact Id, deleted, id, inbox, last Message Body, last Message Date, last Message Type, location Id, starred, unread Count, user Id

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Assigned User ID as string
contactId	string	Required within parent	Contact ID as string
deleted	boolean	Required within parent	Deleted status of the conversation.
id	string	Optional	Contact ID as string
inbox	boolean	Optional	Inbox status of the conversation.
lastMessageBody	string	Optional	Last message body as string
lastMessageDate	string	Optional	Last message date as UTC
lastMessageType	string	Optional	Type of the last message sent/received in the conversation. Known values: TYPE_CALL, TYPE_SMS, TYPE_RCS, TYPE_EMAIL, TYPE_SMS_REVIEW_REQUEST, TYPE_WEBCHAT, TYPE_SMS_NO_SHOW_REQUEST, TYPE_CAMPAIGN_SMS, TYPE_CAMPAIGN_CALL, TYPE_CAMPAIGN_EMAIL, TYPE_CAMPAIGN_VOICEMAIL, TYPE_FACEBOOK, TYPE_CAMPAIGN_FACEBOOK, TYPE_CAMPAIGN_MANUAL_CALL, TYPE_CAMPAIGN_MANUAL_SMS, TYPE_GMB, TYPE_CAMPAIGN_GMB, TYPE_REVIEW, TYPE_INSTAGRAM, TYPE_WHATSAPP, TYPE_CUSTOM_SMS, TYPE_CUSTOM_EMAIL, TYPE_CUSTOM_PROVIDER_SMS, TYPE_CUSTOM_PROVIDER_EMAIL, TYPE_IVR_CALL, TYPE_ACTIVITY_CONTACT, TYPE_ACTIVITY_INVOICE, TYPE_ACTIVITY_PAYMENT, TYPE_ACTIVITY_OPPORTUNITY, TYPE_LIVE_CHAT, TYPE_LIVE_CHAT_INFO_MESSAGE, TYPE_ACTIVITY_APPOINTMENT, TYPE_FACEBOOK_COMMENT, TYPE_INSTAGRAM_COMMENT, TYPE_CUSTOM_CALL, TYPE_INTERNAL_COMMENT, TYPE_ACTIVITY_EMPLOYEE_ACTION_LOG, TYPE_TIKTOK, TYPE_TIKTOK_COMMENT, TYPE_ACTIVITY_WHATSAPP, TYPE_FORM_SUBMISSION, TYPE_SMS_REACTION
locationId	string	Required within parent	Location ID as string
starred	boolean	Optional	Starred status of the conversation.
unreadCount	JSON	Optional
unreadCount (anyOf 1)	number	Alternative	Count of unread messages in the conversation
unreadCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
userId	string	Optional	User ID as string

Update email message status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Request body to update the delivery status of an email message. `status` is required. `events` and `recipients` are optional and may be included together with `status`. - Use `events` to report aggregate delivery metrics (delivered count, open count, etc.). - Use `recipients` to track per-recipient delivery outcomes for multi-recipient emails. - Use `status` to set the overall message status. Multiple calls are additive — event counters are merged, recipient statuses are upserted, and the message status is overwritten.
events	JSON	Optional	Aggregate delivery event counters. Counters are merged into existing values. The API automatically infers related events (e.g., reporting `clicked` will also set `opened` and `delivered` if not already present). See the endpoint description for the full inference rules.
events (allOf 1)	Model	All variants apply	Expand Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed
recipients	array	Optional	Per-recipient delivery statuses. Each entry maps a recipient email address to a delivery status. Entries are upserted — if a recipient already has a status, it will be overwritten with the new value.
recipients[]	Model	Each item	Expand Update email message status — request body — body recipients item
status	string	Required within parent	The overall status of the email message. Required on every request. For emails with multiple recipients, consider using the `recipients` array for granular tracking and this field for the aggregate status. One of: pending, scheduled, sent, delivered, read, undelivered, connected, failed, opened, clicked

Referenced models: Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed, Update email message status — request body — body recipients item

Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed

Field	Type	Presence	Description and constraints
$	object	Root	Aggregate delivery event counters for the email message. Values are merged into existing stored counters (additive update, not replacement). A value of `0` is treated as a no-op and will not reset the stored counter. Only include fields you want to update. Provider-specific counters such as `permanent_fail`, `temporary_fail`, and `esp_isp_block` may be sent using those snake_case keys. Additional keys: see wildcard field
accepted	integer	Optional	Number of messages accepted by the receiving mail server for delivery. Automatically inferred (set to 1) when `delivered`, `permanent_fail`, or `temporary_fail` events are reported.
clicked	integer	Optional	Number of link click events within the email body. Triggers automatic inference of both `opened` and `delivered`.
complained	integer	Optional	Number of spam complaint events (e.g., recipient marked the email as spam). Triggers automatic inference of `opened` and `delivered`.
delivered	integer	Optional	Number of successful deliveries — the recipient mail server accepted the message. Automatically inferred (set to 1) when `opened`, `clicked`, `complained`, `unsubscribed`, or `replied` events are reported.
failed	integer	Optional	Total number of delivery failures (includes both permanent and temporary). For more granular failure tracking, use `permanent_fail` and `temporary_fail` instead.
opened	integer	Optional	Number of unique open events (typically tracked via a tracking pixel). Automatically inferred (set to 1) when `clicked`, `complained`, `unsubscribed`, or `replied` events are reported, provided open tracking is enabled on the email.
rejected	integer	Optional	Number of messages rejected outright by the receiving mail server (before acceptance).
replied	integer	Optional	Number of reply events. Triggers automatic inference of both `opened` (if open tracking is enabled) and `delivered`.
stored	integer	Optional	Number of messages stored by the email service provider (ESP-specific event).
unsubscribed	integer	Optional	Number of unsubscribe events triggered by the recipient. Triggers automatic inference of `opened` and `delivered`.
$.*	integer	Additional keys	Additional provider event counter (merged into stored values).

Update email message status — request body — body recipients item

Field	Type	Presence	Description and constraints
$	object	Root	Delivery status for an individual recipient of a multi-recipient email. Each entry is keyed by the recipient's email address and tracks their specific delivery outcome independently from the aggregate event counters.
emailId	string	Required within parent	The recipient's email address. This is used as the key to store and update the per-recipient status. Must match one of the original recipients of the email.
failReason	string	Optional	Human-readable reason for the delivery failure. Only applicable when `status` is `failed`. Examples: "Mailbox not found", "Quota exceeded", "Blocked by recipient server".
status	string	Required within parent	The delivery status for this specific recipient. Common values for status updates: `delivered` (successfully delivered), `failed` (delivery failed — provide `failReason`), `opened` (recipient opened the email), `clicked` (recipient clicked a link). One of: pending, scheduled, sent, delivered, read, undelivered, connected, failed, opened, clicked

Update email message status — response body

Field	Type	Presence	Description and constraints
$	object	Root	Response returned after successfully updating the email message status.
message	string	Required within parent	Human-readable result message.
success	boolean	Required within parent	Whether the status update was persisted successfully.

Update message status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
emailMessageId	string	Optional	Email message Id
error	JSON	Optional	Error object from the conversation provider
error (allOf 1)	Model	All variants apply	Expand Update message status — request body — body error code, message, type
recipients	array	Optional	Email delivery status for additional email recipients.
recipients[]	string	Each item
status	string	Required within parent	Message status One of: delivered, failed, pending, read

Referenced models: Update message status — request body — body error code, message, type

Update message status — request body — body error code, message, type

Field	Type	Presence	Description and constraints
$	object	Root
code	string	Required within parent	Error Code
message	string	Required within parent	Error Message
type	string	Required within parent	Error Type

Upload file attachments — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
attachmentUrls	array	Required within parent	Array of attachment URLs to upload for the conversation
attachmentUrls[]	string	Each item
chatServiceSid	string	Optional	Twilio chat service SID for group SMS uploads
contactId	string	Required within parent	Contact Id
conversationId	string	Required within parent	Conversation Id
isGroupSms	string	Optional	Flag to indicate group SMS upload flow. When true, only 1 file upload is allowed per request.
locationId	string	Required within parent	Location ID associated with the upload request

Upload file attachments — response body

Field	Type	Presence	Description and constraints
$	object	Root
twilioMediaSids	array	Optional	Twilio media SIDs for group SMS (when isGroupSms=true)
twilioMediaSids[]	string	Each item
uploadedFiles	object	Required within parent	Map of uploaded file names to their accessible URLs