Send Message

Beta
POST/v1/messaging/conversations/{id}/messages

Idempotent with Idempotency-Key header. Learn more

Posts a message to a conversation.

With mode = send the message is delivered — immediately, or queued when scheduled_at is set — and a retry of an immediate send with the same client_message_id returns the original message rather than posting it twice. With mode = draft the message is proposed as a reply to the customer and held for a teammate to approve instead of being sent, and channel is required.

Sending requires you to be an active participant allowed to post: view-only participants cannot post, and in a direct message neither side of a block can. On a customer-facing case, replying to the customer moves the case to waiting on the customer, and proposing a draft moves it to awaiting approval.

Permissions requiredValues:messaging:create
The role behind your API key or agent must grant every one of these permissions.
idstring

Conversation ID.

include[]optional arrayenumValues:senderauthorresource

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

bodystring

Message body.

Required unless the message carries at least one attachment or a resource link.

modeoptional stringenumValues:senddraft

Whether to deliver the message now or hold it as a customer-reply draft. Defaults to send.

  • send: delivers the message, immediately or at scheduled_at.
  • draft: proposes a reply to the customer on a customer-facing case and holds it for a teammate to approve before it goes out. Requires channel.

A draft is built from body, subject, channel, and source_thread_message_id only — attachments, mentions, copied recipients, resource links, replies, and scheduling are not carried onto it.

channeloptional stringenumValues:messageemail

The channel a draft will be sent over once it is approved (mode = draft).

  • message: appears in the customer's conversation timeline.
  • email: goes out as an email from the inbox the case is bridged to. Falls back to the conversation timeline if the case has no bridged inbox.
source_thread_message_idoptional string

The internal thread message a draft is composed from, when drafting from a thread (mode = draft).

client_message_idstring

Client-supplied dedupe key.

Repeating an immediate send with the same value returns the message created by the first request instead of posting a second one, so a retry after a network failure is safe. Required when sending (mode = send); ignored for drafts.

audienceoptional stringenumValues:internalcustomer

Who the message is addressed to on a customer-facing case. Defaults to internal.

  • customer: a reply the customer sees, shown to them as coming from "Customer Service" and delivered as email when the case is bridged to an inbox.
  • internal: a team-only note the customer never sees.

Messages are team-only unless you ask for customer, so an internal note can never leak by omission. Asking for customer on a conversation that has no customer is rejected.

On a case bridged to an email inbox, a customer reply goes out as mail carrying only the body, subject, and copied recipients — attachments, mentions, resource links, and replies are dropped.

subjectoptional string

The subject line for a customer reply sent by email.

When omitted, the reply goes out as "Re:" the case title.

ccoptional array of string

Additional email addresses to copy on a customer reply sent by email.

scheduled_atoptional string (date-time)

When set, hold the message and deliver it at this future time instead of sending it now.

Only the body is carried into a scheduled send — attachments, mentions, copied recipients, resource links, replies, and audience are dropped, and it is delivered as an ordinary team-visible message. If you are no longer an active participant when it comes due, it is canceled instead of sent.

reply_to_message_idoptional string

The message this one is a reply to.

link_resource_typeoptional stringenumValues:accountactorentity

Type of a resource to link in the message, paired with link_resource_id.

Linking a record lets clients render the message as a reference to it. A link counts in place of text, so a message may consist of nothing but the link.

link_resource_idoptional string

ID of a resource to link in the message, paired with link_resource_type.

attachmentsoptional array of object

Attachments to include with the message.

kindstringenumValues:fileimagelink

What is being attached.

  • file: a document you uploaded to object storage first.
  • image: an uploaded image, rendered inline in the conversation.
  • link: an external web address, with nothing stored on our side.
  • resource: a reference to an in-app record, such as an order.
s3_keyoptional string

The key you uploaded the file to, taken from the upload-url response (file and image).

The key must be one minted for this conversation and the file must already be uploaded, otherwise the send is rejected.

filenameoptional string

The filename to display for the attachment (file and image).

content_typeoptional string

The MIME content type of the uploaded file (file and image).

size_bytesoptional integer

The size of the uploaded file in bytes (file and image).

urloptional string

The web address being shared (link).

resource_typeoptional string

The type of the record being referenced, paired with resource_id (resource).

resource_idoptional string

The id of the record being referenced, paired with resource_type (resource).

mentionsoptional array of string

Account user ids explicitly @mentioned in the message.

A mention notifies the person even when they have muted the conversation.

idstring

Message ID.

objectstringenumValues:chat_message

Resource type identifier.

kindstringenumValues:chatsystem_eventagent

What this message represents.

  • chat: written by a person.
  • system_event: a record of something that happened in the conversation, such as someone joining or a record being linked.
  • agent: written by an AI agent taking part in the conversation.
  • scheduled: came from a send queued ahead of time.
  • alert: an automated alert surfaced in the conversation.
  • email: a message carried over the case's bridged email thread, either one that arrived from the customer or a reply sent back out to them.
statusstringenumValues:draftscheduledsent

Where the message stands in its life.

  • draft: a proposed reply to the customer, still editable and waiting for approval before anyone outside sees it.
  • scheduled: queued to go out at a future time.
  • sent: delivered, and part of the conversation everyone reads.
  • canceled: a scheduled message stopped before it went out.
  • rejected: a draft discarded instead of being sent.
  • failed: a scheduled message that could not be delivered.
  • superseded: a draft replaced by a newer one for the same thread.

Only a sent message occupies a place in the conversation; the others are records of messages that never reached it.

visibilitystringenumValues:internalexternalsystem

Who can see this message.

  • internal: a note only your team can see.
  • external: sent to or received from an outside party, such as the customer on a support case, and part of the official record of that exchange.
  • system: an event both your team and the customer see.

A customer reading their own case is never served internal messages.

conversationconversationExpandablenullable

The conversation this message belongs to.

idstring

Conversation ID.

objectstringenumValues:conversation

Resource type identifier.

typestringenumValues:direct_messagegroupsystem

What kind of conversation this is.

  • direct_message: a 1:1 thread between two users.
  • group: a named thread with multiple user or agent members (including customer-facing support cases).
  • system: a system channel that delivers automated account alerts.
audiencestringenumValues:internalcustomer

Whether this is a team-only conversation (internal) or a customer-facing case (customer).

A customer never sees an internal conversation, even one that is about them; within a customer case they see only the messages that were sent to them, not the team's internal notes on the case.

titlestringnullable

The display title of a group conversation.

Direct messages carry no stored title; clients derive one from the participants.

workflow_statusstringnullableenumValues:newopenwaiting_internal

The triage lane of a customer-facing case.

Only conversations with a customer audience have a triage lane. It drives the support inbox and is independent of status, which is about visibility rather than progress.

  • new: opened but not yet triaged.
  • open: actively being worked.
  • waiting_internal: blocked on the internal team.
  • waiting_external: blocked on an external reply.
  • needs_approval: a drafted reply is awaiting human approval.
  • resolved: closed out.
groupmessaging_groupnullable

The reusable roster this conversation was started from.

This is provenance only: the roster's members were copied into the conversation when it was created, so later edits to the roster never add or remove participants here, and deleting the roster only clears this reference.

Always returned as null in this endpoint.
statusstringenumValues:activearchivedhidden

The conversation's state from the caller's point of view.

  • active: a normal, visible conversation.
  • archived: archived for the whole account.
  • hidden: the caller dismissed the conversation from their own list while everyone else still sees it, which takes precedence over an account-level archive.
legal_holdstringenumValues:releasedheld

Whether the conversation is under legal hold.

While held, the conversation is exempt from automatic retention purging and from redaction until the hold is released.

assigneeactornullable

The owner of the case: either a user actor (an individual team member) or a group actor (a team).

Always returned as null in this endpoint.
participantslistExpandablenullable

The participants of the conversation.

Only current members are listed; anyone who left or was removed is omitted, even though their past messages remain in the thread.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of conversation_participant

Resources in this page.

idstring

Participant ID.

objectstringenumValues:conversation_participant

Resource type identifier.

typestringenumValues:useragentsystem

The kind of participant.

  • user: an account user (a teammate).
  • agent: an AI agent.
  • system: the system itself, which posts automated messages.
  • customer: an external customer in a support case.
rolestringenumValues:owneradminmember

The participant's permission level in the conversation.

  • owner: can rename or delete the conversation and manage its members and their roles.
  • admin: can add or remove members and rename the conversation.
  • member: can post, react, mute, and leave.
  • viewer: read-only access.
membershipstringenumValues:activeleftremoved

The participant's membership in the conversation.

  • active: currently a member.
  • left: voluntarily left the conversation.
  • removed: removed by an admin.
  • hidden: still a member but has hidden the conversation from their own list.

Membership records are kept rather than deleted, so re-adding someone who left or was removed reactivates their original record and their earlier messages stay attributed to them.

notificationsstringenumValues:unmutedmuted

The participant's notification preference for the conversation.

  • unmuted: receives notifications for new messages.
  • muted: new-message notifications are suppressed, though a direct @mention still raises an in-app alert (never an email), and the conversation still counts toward the unread total.
actoractornullable

The user or agent behind this participant.

A customer participant resolves to the user actor of the person who opened the case; the system participant that posts automated messages has no actor.

Always returned as null in this endpoint.
agent_trigger_policystringnullableenumValues:mentionkeywordalways

For agent participants, when the agent is invoked in response to messages.

  • mention: only when the agent is @mentioned.
  • keyword: when a message contains one of the agent's trigger keywords.
  • always: on every human message in the conversation.
agent_trigger_keywordsarray of string

For agent participants with a keyword or mention policy, the keywords that trigger it.

Matching is case-insensitive and looks anywhere in the message body: under keyword the bare word is matched, under mention it must appear as @keyword. Replying directly to one of the agent's own messages always reaches it, so an agent with no keywords still answers replies but nothing else.

read_cursorread_cursor

The participant's read position in the conversation (read receipts): how far they have read.

Always returned as null in this endpoint.
topicentitynullable

The app record this conversation is anchored to, such as a sales order.

Anchored conversations surface as the discussion thread on that record.

Always returned as null in this endpoint.
unreadinteger

Number of messages the caller has not yet read.

last_message_atstring (date-time)nullable

When the most recent message was sent.

last_messagechat_messageExpandablenullable

The most recent message in the conversation.

idstring

Message ID.

objectstringenumValues:chat_message

Resource type identifier.

kindstringenumValues:chatsystem_eventagent

What this message represents.

  • chat: written by a person.
  • system_event: a record of something that happened in the conversation, such as someone joining or a record being linked.
  • agent: written by an AI agent taking part in the conversation.
  • scheduled: came from a send queued ahead of time.
  • alert: an automated alert surfaced in the conversation.
  • email: a message carried over the case's bridged email thread, either one that arrived from the customer or a reply sent back out to them.
statusstringenumValues:draftscheduledsent

Where the message stands in its life.

  • draft: a proposed reply to the customer, still editable and waiting for approval before anyone outside sees it.
  • scheduled: queued to go out at a future time.
  • sent: delivered, and part of the conversation everyone reads.
  • canceled: a scheduled message stopped before it went out.
  • rejected: a draft discarded instead of being sent.
  • failed: a scheduled message that could not be delivered.
  • superseded: a draft replaced by a newer one for the same thread.

Only a sent message occupies a place in the conversation; the others are records of messages that never reached it.

visibilitystringenumValues:internalexternalsystem

Who can see this message.

  • internal: a note only your team can see.
  • external: sent to or received from an outside party, such as the customer on a support case, and part of the official record of that exchange.
  • system: an event both your team and the customer see.

A customer reading their own case is never served internal messages.

conversationconversationnullable

The conversation this message belongs to.

Always returned as null in this endpoint.
sequenceinteger

The message's position in the conversation timeline, counting up from the first message.

A sequence is assigned only when a message is delivered, so a draft or a not-yet-sent scheduled message reports 0. Listing a conversation's messages pages backwards through this ordering.

bodystringnullable

Message body.

A message made up of nothing but attachments or a linked record carries no body, and a deleted message has its body cleared.

subjectstringnullable

The email subject line.

On an email-bridged case, this is the subject of the inbound email, or the subject a customer reply is sent out with.

senderactornullable

The party the message is displayed as coming from.

On a customer-facing case the customer sees every reply from your side as a single branded "Customer Service" party rather than the individual person or agent behind it, and an inbound email is shown as the outside address it arrived from. Everywhere else this is the user or agent that wrote the message. Pure system messages have no sender.

Always returned as null in this endpoint.
authoractornullable

The user or agent that actually wrote the message.

Absent on system messages, and on a vendor-side reply read by a customer — the real author behind the branded "Customer Service" party is never revealed to them.

Always returned as null in this endpoint.
attachmentslistnullable

Files, images, links, or resources attached to the message.

Always returned as null in this endpoint.
reply_tochat_messagenullable

The message this one replies to.

Always returned as null in this endpoint.
resourceentitynullable

The record this message links to, such as the order it is about.

Always returned as null in this endpoint.
channelstringenumValues:messageemail

How the message reached its audience, or how a draft will be sent once it is approved.

  • message: appears in the conversation itself.
  • email: goes out as email on the thread of the inbox the case is bridged to.
scheduled_atstring (date-time)nullable

When a message queued for a future send is due to go out.

agent_runagent_runnullable

The agent run that produced this message, for deep-linking from an agent reply to its run.

Always returned as null in this endpoint.
streaming_statestringnullableenumValues:streamingcomplete

The streaming state of an agent reply.

streaming means the body is still being generated and keeps growing as realtime updates arrive; complete means it is final.

client_message_idstringnullable

The dedupe key the client supplied when sending, echoed back so an optimistic local copy can be matched to the stored message.

edited_atstring (date-time)nullable

When the message was last edited.

deleted_atstring (date-time)nullable

When the message was deleted.

A deleted message keeps its place in the timeline with its body cleared, so surrounding ordering and replies stay intact.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

agent_run_failedboolean

Whether this message is an agent reply reporting that the agent's run failed.

The body explains the failure to the reader rather than answering the request.

agent_error_codestringnullableenumValues:expired_tokenapi_key_expiredapi_key_revoked

Machine-readable reason an agent reply failed.

A client can react to the specific code rather than just showing the body — agent_spending_cap_reached, for example, is a cue to offer raising the agent spending limit.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

sequenceinteger

The message's position in the conversation timeline, counting up from the first message.

A sequence is assigned only when a message is delivered, so a draft or a not-yet-sent scheduled message reports 0. Listing a conversation's messages pages backwards through this ordering.

bodystringnullable

Message body.

A message made up of nothing but attachments or a linked record carries no body, and a deleted message has its body cleared.

subjectstringnullable

The email subject line.

On an email-bridged case, this is the subject of the inbound email, or the subject a customer reply is sent out with.

senderactorExpandablenullable

The party the message is displayed as coming from.

On a customer-facing case the customer sees every reply from your side as a single branded "Customer Service" party rather than the individual person or agent behind it, and an inbound email is shown as the outside address it arrived from. Everywhere else this is the user or agent that wrote the message. Pure system messages have no sender.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

  • user: a human user account.
  • api_key: a programmatic caller authenticating with an API key.
  • agent: an automated agent acting on the account's behalf.
  • group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
authoractorExpandablenullable

The user or agent that actually wrote the message.

Absent on system messages, and on a vendor-side reply read by a customer — the real author behind the branded "Customer Service" party is never revealed to them.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

  • user: a human user account.
  • api_key: a programmatic caller authenticating with an API key.
  • agent: an automated agent acting on the account's behalf.
  • group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
attachmentslistExpandablenullable

Files, images, links, or resources attached to the message.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of message_attachment

Resources in this page.

idstring

Attachment ID.

objectstringenumValues:message_attachment

Resource type identifier.

kindstringenumValues:fileimagelink

The kind of attachment, which determines how it is stored and which of the fields below are populated.

  • file: an uploaded non-image file.
  • image: an uploaded image.
  • link: an external URL reference, with no stored file.
  • resource: a reference to an in-app resource, such as an order.
filenamestringnullable

The filename the attachment was uploaded under.

Carried only by file and image attachments.

content_typestringnullable

The MIME type of the uploaded content.

Carried only by file and image attachments.

size_bytesintegernullable

The size of the uploaded content in bytes.

Carried only by file and image attachments, and only when the sender supplied it with the message.

urlstringnullable

Where to fetch the attachment: a signed download URL for file and image attachments, or the target address for link attachments.

Download URLs are signed for one hour and regenerated each time the message is read, so follow the URL promptly instead of persisting it. resource attachments have no URL — use resource to resolve them.

resourceentitynullable

The in-app record a resource attachment points to, such as a sales order.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

reply_tochat_messageExpandablenullable

The message this one replies to.

idstring

Message ID.

objectstringenumValues:chat_message

Resource type identifier.

kindstringenumValues:chatsystem_eventagent

What this message represents.

  • chat: written by a person.
  • system_event: a record of something that happened in the conversation, such as someone joining or a record being linked.
  • agent: written by an AI agent taking part in the conversation.
  • scheduled: came from a send queued ahead of time.
  • alert: an automated alert surfaced in the conversation.
  • email: a message carried over the case's bridged email thread, either one that arrived from the customer or a reply sent back out to them.
statusstringenumValues:draftscheduledsent

Where the message stands in its life.

  • draft: a proposed reply to the customer, still editable and waiting for approval before anyone outside sees it.
  • scheduled: queued to go out at a future time.
  • sent: delivered, and part of the conversation everyone reads.
  • canceled: a scheduled message stopped before it went out.
  • rejected: a draft discarded instead of being sent.
  • failed: a scheduled message that could not be delivered.
  • superseded: a draft replaced by a newer one for the same thread.

Only a sent message occupies a place in the conversation; the others are records of messages that never reached it.

visibilitystringenumValues:internalexternalsystem

Who can see this message.

  • internal: a note only your team can see.
  • external: sent to or received from an outside party, such as the customer on a support case, and part of the official record of that exchange.
  • system: an event both your team and the customer see.

A customer reading their own case is never served internal messages.

conversationconversationExpandablenullable

The conversation this message belongs to.

Always returned as null in this endpoint.
sequenceinteger

The message's position in the conversation timeline, counting up from the first message.

A sequence is assigned only when a message is delivered, so a draft or a not-yet-sent scheduled message reports 0. Listing a conversation's messages pages backwards through this ordering.

bodystringnullable

Message body.

A message made up of nothing but attachments or a linked record carries no body, and a deleted message has its body cleared.

subjectstringnullable

The email subject line.

On an email-bridged case, this is the subject of the inbound email, or the subject a customer reply is sent out with.

senderactorExpandablenullable

The party the message is displayed as coming from.

On a customer-facing case the customer sees every reply from your side as a single branded "Customer Service" party rather than the individual person or agent behind it, and an inbound email is shown as the outside address it arrived from. Everywhere else this is the user or agent that wrote the message. Pure system messages have no sender.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

  • user: a human user account.
  • api_key: a programmatic caller authenticating with an API key.
  • agent: an automated agent acting on the account's behalf.
  • group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
authoractorExpandablenullable

The user or agent that actually wrote the message.

Absent on system messages, and on a vendor-side reply read by a customer — the real author behind the branded "Customer Service" party is never revealed to them.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

  • user: a human user account.
  • api_key: a programmatic caller authenticating with an API key.
  • agent: an automated agent acting on the account's behalf.
  • group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
attachmentslistExpandablenullable

Files, images, links, or resources attached to the message.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of message_attachment

Resources in this page.

idstring

Attachment ID.

objectstringenumValues:message_attachment

Resource type identifier.

kindstringenumValues:fileimagelink

The kind of attachment, which determines how it is stored and which of the fields below are populated.

  • file: an uploaded non-image file.
  • image: an uploaded image.
  • link: an external URL reference, with no stored file.
  • resource: a reference to an in-app resource, such as an order.
filenamestringnullable

The filename the attachment was uploaded under.

Carried only by file and image attachments.

content_typestringnullable

The MIME type of the uploaded content.

Carried only by file and image attachments.

size_bytesintegernullable

The size of the uploaded content in bytes.

Carried only by file and image attachments, and only when the sender supplied it with the message.

urlstringnullable

Where to fetch the attachment: a signed download URL for file and image attachments, or the target address for link attachments.

Download URLs are signed for one hour and regenerated each time the message is read, so follow the URL promptly instead of persisting it. resource attachments have no URL — use resource to resolve them.

resourceentitynullable

The in-app record a resource attachment points to, such as a sales order.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

reply_tochat_messageExpandablenullable

The message this one replies to.

Always returned as null in this endpoint.
resourceentityExpandablenullable

The record this message links to, such as the order it is about.

Always returned as null in this endpoint.
channelstringenumValues:messageemail

How the message reached its audience, or how a draft will be sent once it is approved.

  • message: appears in the conversation itself.
  • email: goes out as email on the thread of the inbox the case is bridged to.
scheduled_atstring (date-time)nullable

When a message queued for a future send is due to go out.

agent_runagent_runExpandablenullable

The agent run that produced this message, for deep-linking from an agent reply to its run.

Always returned as null in this endpoint.
streaming_statestringnullableenumValues:streamingcomplete

The streaming state of an agent reply.

streaming means the body is still being generated and keeps growing as realtime updates arrive; complete means it is final.

client_message_idstringnullable

The dedupe key the client supplied when sending, echoed back so an optimistic local copy can be matched to the stored message.

edited_atstring (date-time)nullable

When the message was last edited.

deleted_atstring (date-time)nullable

When the message was deleted.

A deleted message keeps its place in the timeline with its body cleared, so surrounding ordering and replies stay intact.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

agent_run_failedboolean

Whether this message is an agent reply reporting that the agent's run failed.

The body explains the failure to the reader rather than answering the request.

agent_error_codestringnullableenumValues:expired_tokenapi_key_expiredapi_key_revoked

Machine-readable reason an agent reply failed.

A client can react to the specific code rather than just showing the body — agent_spending_cap_reached, for example, is a cue to offer raising the agent spending limit.

resourceentityExpandablenullable

The record this message links to, such as the order it is about.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

channelstringenumValues:messageemail

How the message reached its audience, or how a draft will be sent once it is approved.

  • message: appears in the conversation itself.
  • email: goes out as email on the thread of the inbox the case is bridged to.
scheduled_atstring (date-time)nullable

When a message queued for a future send is due to go out.

agent_runagent_runExpandablenullable

The agent run that produced this message, for deep-linking from an agent reply to its run.

idstring

Agent run ID.

objectstringenumValues:agent_run

Resource type identifier.

trigger_typestringenumValues:scheduledmanualevent

How this run was initiated.

  • scheduled: started by the agent's cron schedule.
  • event: started in response to a platform event.
  • manual: started by an explicit request; see triggered_by.
  • chat: started by a message in a conversation, with the agent's reply posted back into that conversation.
statusstringenumValues:pendingrunningcompleted

Current run status.

  • pending: queued but not yet started.
  • running: currently executing.
  • awaiting_input: paused, waiting for user input before continuing.
  • awaiting_approval: paused, waiting for a pending action to be approved.
  • completed: finished successfully.
  • failed: stopped after an error; see error_message.
  • cancelled: stopped before completion by a user.
definitionagent_definitionnullable

The agent definition this run executes.

Always returned as null in this endpoint.
inputobjectnullable

Input provided to the agent at the start of the run.

The shape depends on what started the run; a manually triggered run records {"message": "<your input>"}.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

outputobjectnullable

Final output produced by the agent.

Present once the agent has produced a result, including on a run that paused for more input or was cancelled part-way through. A run that has not produced one yet carries an empty object.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

error_messagestringnullable

Error message if the run failed.

triggered_byactornullable

Actor that triggered this run.

Set only for runs started through the Trigger Agent Run endpoint; runs started by a schedule, a platform event, or a chat message have no triggering actor.

Always returned as null in this endpoint.
started_atstring (date-time)nullable

When the run started executing.

completed_atstring (date-time)nullable

When the run completed.

duration_msintegernullable

How long the run took, in milliseconds.

actionslistnullable

Tool invocations the agent made during this run.

Includes calls that were held for human review and never executed, so an entry here does not by itself mean the tool ran.

Always returned as null in this endpoint.
stepslistnullable

Step-by-step timeline of what happened during the run.

Ordered by sequence, oldest first.

Always returned as null in this endpoint.
created_atstring (date-time)

When this run was created.

updated_atstring (date-time)

When this run was last updated.

streaming_statestringnullableenumValues:streamingcomplete

The streaming state of an agent reply.

streaming means the body is still being generated and keeps growing as realtime updates arrive; complete means it is final.

client_message_idstringnullable

The dedupe key the client supplied when sending, echoed back so an optimistic local copy can be matched to the stored message.

edited_atstring (date-time)nullable

When the message was last edited.

deleted_atstring (date-time)nullable

When the message was deleted.

A deleted message keeps its place in the timeline with its body cleared, so surrounding ordering and replies stay intact.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

agent_run_failedboolean

Whether this message is an agent reply reporting that the agent's run failed.

The body explains the failure to the reader rather than answering the request.

agent_error_codestringnullableenumValues:expired_tokenapi_key_expiredapi_key_revoked

Machine-readable reason an agent reply failed.

A client can react to the specific code rather than just showing the body — agent_spending_cap_reached, for example, is a cue to offer raising the agent spending limit.

Responses

201

Successful response for Send Message