---
title: "Create a message"
method: POST
path: "/api/tickets/{ticket_id}/messages"
tags: ["Ticket Messages"]
---

# Create a message

`POST /api/tickets/{ticket_id}/messages`

## Request

- Base URL: `https://your-domain.gorgias.com`
- URL: `https://your-domain.gorgias.com/api/tickets/{ticket_id}/messages`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/gorgias/apis/gorgias-rest-api/docs/api/tickets/:ticket_id/messages/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a message and either:
  - not send it if the attribute `sent_datetime` is filled.
  If you import a message that was already sent, make sure to set this value.
  - send it to the recipients if the attribute `sent_datetime` is empty.
  - add it to the ticket as an internal note if you specified this channel.
  Internal notes are not sent to your customers.

When a message is created, it does not mean that this one has been sent because the creation and sending process are decoupled. Messages are basically sent asynchronously. Once a message has been sent, Gorgias will automatically update the message to fill the time when it was sent (`sent_datetime`).

## Path parameters

- `ticket_id` integer, required

## Query parameters

- `action` 'force' | 'retry' | 'cancel'

## Headers

- `If-Unmodified-Since` string

## Request body

- CreateMessage
  - `actions` union[]: Actions associated with the message
    - union
      - string
      - integer
      - number
      - boolean
      - object
      - unknown[]
        - unknown
  - `attachments` CreateMessageAttachment[]: Attachments associated with the message
    - `url` string, uri, required
    - `name` string, required
    - `size` integer
    - `content_type` string, required
    - `public` boolean
    - `extra` union
      - string
      - integer
      - number
      - boolean
      - object
      - unknown[]
        - unknown
  - `body_html` string: HTML version of the body of the message
  - `body_text` string: Text version of the body of the message
  - `channel` union, required: Channel used to send the message
    - 'aircall' | 'api' | 'chat' | 'contact_form' | 'email' | 'facebook' | 'facebook-mention' | 'facebook-messenger' | 'facebook-recommendations' | 'help-center' | 'instagram-ad-comment' | 'instagram-comment' | 'instagram-direct-message' | 'instagram-mention' | 'internal-note' | 'phone' | 'sms' | 'twitter' | 'twitter-direct-message' | 'whatsapp' | 'yotpo-review'
    - string
  - `created_datetime` string, date-time: When the message was created
  - `deleted_datetime` string, date-time: When the message was deleted
  - `external_id` string: ID of the message in a foreign system (Aircall, Zendesk, etc...). This field is not used by Gorgias, feel free to set it as you wish.
  - `failed_datetime` string, date-time: When the message failed to be sent. Messages that couldn't be sent can be resent.
  - `from_agent` boolean, required: Whether the message was sent by your company
  - `headers` object: Headers of the message
  - `integration_id` integer: ID of the Integration used to send the message
  - `last_sending_error` CreateMessageLastSendingError
    - `error` string, required
  - `macros` CreateMessageMacro[]: Macros used to compose the message
    - `id` integer, required
  - `message_id` string: ID of the message on the service that sent the message. It can be the ID of an email, a Messenger message, a Facebook comment, etc...
  - `meta` CreateMessageMeta
    - `relevant_content_indexes` integer[]
  - `opened_datetime` string, date-time: When the message was seen by its recipient
  - `public` boolean: Whether the message is public. Only internal notes are private.
  - `sent_datetime` string, date-time: When the message was sent. If omitted, the message will be sent by Gorgias.
  - `source` CreateMessageSource
    - `type` 'aircall' | 'api' | 'app' | 'custom-chat' | 'chat' | 'chat-contact-form' | 'chat-offline-capture' | 'contact-form' | 'email' | 'facebook' | 'facebook-comment' | 'facebook-mention-comment' | 'facebook-mention-post' | 'facebook-message' | 'facebook-messenger' | 'facebook-post' | 'facebook-review' | 'facebook-review-comment' | 'form' | 'google-business-messages' | 'help-center' | 'help-center-contact-form' | 'helpdesk' | 'instagram' | 'instagram-ad-comment' | 'instagram-ad-media' | 'instagram-comment' | 'instagram-direct-message' | 'instagram-media' | 'instagram-mention-comment' | 'instagram-mention-media' | 'internal-note' | 'ottspott-call' | 'phone' | 'rule' | 'self_service' | 'shopify' | 'sms' | 'system-message' | 'tiktok-shop' | 'twilio' | 'twitter-direct-message' | 'twitter-mention-tweet' | 'twitter-quoted-tweet' | 'twitter-tweet' | 'whatsapp-message' | 'yotpo-review' | 'yotpo-review-private-comment' | 'yotpo-review-public-comment'
    - `from` CreateMessageSourcePerson
      - `name` string
      - `address` string
    - `to` CreateMessageSourcePerson[]
      - `name` string
      - `address` string
    - `cc` CreateMessageSourcePerson[]
      - `name` string
      - `address` string
    - `bcc` CreateMessageSourcePerson[]
      - `name` string
      - `address` string
    - `extra` union
      - string
      - integer
      - number
      - boolean
      - object
      - unknown[]
        - unknown
  - `stripped_html` string: HTML version of the body of the message without email signatures and previous replies.
  - `stripped_signature` string: Signature stripped from the body of the message
  - `stripped_text` string: Text version of the body of the message without email signatures and previous replies.
  - `subject` string: Subject of the message
  - `via` 'aircall' | 'api' | 'chat' | 'contact_form' | 'email' | 'facebook' | 'facebook-mention' | 'facebook-messenger' | 'facebook-recommendations' | 'form' | 'helpdesk' | 'help-center' | 'instagram' | 'instagram-ad-comment' | 'instagram-comment' | 'instagram-direct-message' | 'instagram-mention' | 'internal-note' | 'phone' | 'rule' | 'shopify' | 'sms' | 'twilio' | 'twitter' | 'twitter-direct-message' | 'whatsapp' | 'yotpo' | 'yotpo-review' | 'zendesk': How the message has been received or sent from Gorgias
  - `imported` boolean: Whether the message was created by a historical import.
  - `mention_ids` integer[]: List of User IDs to mention along with the internal note.
  - `receiver` CreateMessageCustomerOrUser
    - `id` integer: ID of the customer or user
    - `email` string: Email of the customer or user
    - `name` string: Name of the customer or user
    - `external_id` string: ID of the customer or user in a foreign system (Aircall, Zendesk, etc...). This field is not used by Gorgias, feel free to set it as you wish.
    - `note` string: Note attached to the customer or user
    - `timezone` string: Timezone of the customer or user
    - `language` string: Language of the customer or user
    - `meta` object: Metadata associated with the customer or user. You can use this field to store structured information (key-value data) about the customer or user.
    - `channels` CreateMessageCustomerChannel[]: Channels associated with the customer or user
      - `type` string, required
      - `address` string, required
  - `sender` CreateMessageCustomerOrUser
    - `id` integer: ID of the customer or user
    - `email` string: Email of the customer or user
    - `name` string: Name of the customer or user
    - `external_id` string: ID of the customer or user in a foreign system (Aircall, Zendesk, etc...). This field is not used by Gorgias, feel free to set it as you wish.
    - `note` string: Note attached to the customer or user
    - `timezone` string: Timezone of the customer or user
    - `language` string: Language of the customer or user
    - `meta` object: Metadata associated with the customer or user. You can use this field to store structured information (key-value data) about the customer or user.
    - `channels` CreateMessageCustomerChannel[]: Channels associated with the customer or user
      - `type` string, required
      - `address` string, required

## Response `201`

The created message.

- TicketMessage: A ticket-message represents a message (an email, an SMS, a Facebook comment, chat message, etc..) under a normalized format. There are 3 types of messages: - Outgoing messages: messages sent by your company (by rules or support agents) to your customers. - Incoming messages: messages sent by your [customers](#the-customer-object) to your company. - Internal notes: internal messages sent between support agents ([users](#the-user-object)). Internal notes are not sent/shared with your customers. A ticket-message is associated with only one ticket.
  - `id` integer, required: ID of the message.
  - `uri` string, required: URI of the message.
  - `message_id` string, required: ID of the message on the service that sent the message.It can be the ID of an email, a Messenger message, a Facebook comment, etc...
  - `ticket_id` integer, required: The ID of the ticket the message is associated with.
  - `external_id` string, required: ID of the message in a foreign system (Aircall, Zendesk, etc...). This field is not used by Gorgias, feel free to set it as you wish.
  - `public` boolean: Whether the message was sent/receive by a customer. Internal notes are not public.
  - `channel` union, required: The channel used to send the message.
    - 'aircall' | 'api' | 'chat' | 'contact_form' | 'email' | 'facebook' | 'facebook-mention' | 'facebook-messenger' | 'facebook-recommendations' | 'help-center' | 'instagram-ad-comment' | 'instagram-comment' | 'instagram-direct-message' | 'instagram-mention' | 'internal-note' | 'phone' | 'sms' | 'twitter' | 'twitter-direct-message' | 'whatsapp' | 'yotpo-review'
    - string
  - `via` 'aircall' | 'api' | 'chat' | 'contact_form' | 'email' | 'facebook' | 'facebook-mention' | 'facebook-messenger' | 'facebook-recommendations' | 'form' | 'gorgias_chat' | 'help-center' | 'helpdesk' | 'instagram' | 'instagram-ad-comment' | 'instagram-comment' | 'instagram-direct-message' | 'instagram-mention' | 'internal-note' | 'offline_capture' | 'phone' | 'rule' | 'self_service' | 'shopify' | 'sms' | 'twilio' | 'twitter' | 'twitter-direct-message' | 'whatsapp' | 'yotpo' | 'yotpo-review' | 'zendesk', required
  - `source` TicketMessageSource, required
    - `type` string, required: Describes a more detailed channel information of how the message was sent/received. Either the slug of a non-legacy channel or one of aircall,api,app,chat,chat-contact-form,chat-offline-capture,contact-form,email,facebook-comment,facebook-message,facebook-messenger,facebook-post,facebook-mention-post,facebook-mention-comment,facebook,facebook-review,facebook-review-comment,form,help-center,helpdesk,instagram-ad-comment,instagram-ad-media,instagram-comment,instagram-mention-comment,instagram-media,instagram-mention-media,instagram,instagram-direct-message,internal-note,ottspott-call,phone,rule,self_service,shopify,sms,system-message,twilio,yotpo-review,yotpo-review-public-comment,yotpo-review-private-comment,twitter-tweet,twitter-quoted-tweet,twitter-mention-tweet,twitter-direct-message,help-center-contact-form,whatsapp-message.
    - `to` TicketMessageSourceAddress[]: A list of To addresses. To and From are usually present for most channel types.
      - `name` string
      - `address` string
    - `cc` TicketMessageSourceAddress[]: A list of CC addresses. Only present in an email context.
      - `name` string
      - `address` string
    - `bcc` TicketMessageSourceAddress[]: A list of BCC addresses. Only present in an email context.
      - `name` string
      - `address` string
    - `from` TicketMessageSourceAddress
      - `name` string
      - `address` string
    - `extra` unknown
  - `sender` TicketMessageUserOrCustomer, required
    - `id` integer, required
    - `email` string, required
    - `name` string, required
    - `firstname` string, required
    - `lastname` string, required
    - `meta` unknown, required
  - `auth_customer_identity` TicketMessageAuthCustomerIdentity, required
    - `service` TicketMessageAuthCustomerIdentityService, required
      - `id` string, required: The ID of the service the identity belongs to.
      - `name` string, required: The name of the service the identity belongs to.
    - `identifier` string, required: The ID of the customer related to the service. E.g.: email address, phone number, Shopify customer ID, etc.
  - `integration_id` integer, required: ID of the integration that either received or sent the message.
  - `intents` TicketMessageIntent[], required
    - `name` string, required: The intention the message probably has, example: discount/request
    - `rejected` boolean, required: Whether or not the intent was rejected
    - `is_user_feedback` boolean, required: Whether or not the intent comes from a user feedback
  - `rule_id` integer, required: ID of the rule which sent the message, if any.
  - `from_agent` boolean, required: Whether the message was sent by your company to a customer, or the opposite.
  - `receiver` TicketMessageUserOrCustomer, required
    - `id` integer, required
    - `email` string, required
    - `name` string, required
    - `firstname` string, required
    - `lastname` string, required
    - `meta` unknown, required
  - `subject` string, required: The subject of the message.
  - `body_text` string, required: The full text version of the body of the message, if any.
  - `body_html` string, required: The full HTML version of the body of the message, if any.
  - `body_url` string, required: The URL to download the archived body of the email message. Empty until the body is archived, 30 days after it was sent or received. Only applies to email messages that have stripped bodies.
  - `stripped_text` string, required: The text version of the body of the message without email signatures and previous replies.
  - `stripped_html` string, required: The HTML version of the body of the message without email signatures and previous replies.
  - `stripped_signature` string, required
  - `attachments` TicketMessageAttachment[], required: A list of files attached to the message.
    - `url` string, required: The URL to access to the attached file.
    - `name` string: The name of the file.
    - `size` integer: The size of the file, in bytes.
    - `content_type` string, required: The MIME type of the file.
    - `public` boolean: Whether or not the attachment can be accessed.
    - `extra` unknown
  - `macros` TicketMessageMacro[]: A list of macros.
    - `id` integer, required
  - `actions` object[], required: A list of actions executed before the message was sent. These actions are set by macros.
  - `headers` object: Message headers. Used for email messages.
  - `imported` boolean, required: Whether the message was created by a historical import.
  - `meta` unknown, required
  - `created_datetime` string, date-time, required: When the message was created.
  - `processed_datetime` string, date-time, required: When the message was processed by Gorgias. Differs from `created_datetime` which refers to the external service.
  - `deleted_datetime` string, date-time: When the message was deleted.
  - `sent_datetime` string, date-time, required: When the message was sent. If omitted, the message will be sent by Gorgias.
  - `failed_datetime` string, date-time, required: When the message failed to be sent. Messages that couldn't be sent can be resend.
  - `opened_datetime` string, date-time, required: When the message was opened by the primary receiver.
  - `last_sending_error` TicketMessageSendingError, required
    - `error` string, required
  - `is_retriable` boolean, required: It determines if the message can be retried or not.
  - `replied_by` TicketMessageRepliedByOrTo
    - `integration_id` integer, required: ID of the integration which created the message.
    - `message_id` string, required: ID of the message in Gorgias.
    - `created_datetime` string, date-time, required: When the message was created.
    - `body_text` string, required: The full text version of the body of the message, if any.
    - `source` TicketMessageSource, required
      - `type` string, required: Describes a more detailed channel information of how the message was sent/received. Either the slug of a non-legacy channel or one of aircall,api,app,chat,chat-contact-form,chat-offline-capture,contact-form,email,facebook-comment,facebook-message,facebook-messenger,facebook-post,facebook-mention-post,facebook-mention-comment,facebook,facebook-review,facebook-review-comment,form,help-center,helpdesk,instagram-ad-comment,instagram-ad-media,instagram-comment,instagram-mention-comment,instagram-media,instagram-mention-media,instagram,instagram-direct-message,internal-note,ottspott-call,phone,rule,self_service,shopify,sms,system-message,twilio,yotpo-review,yotpo-review-public-comment,yotpo-review-private-comment,twitter-tweet,twitter-quoted-tweet,twitter-mention-tweet,twitter-direct-message,help-center-contact-form,whatsapp-message.
      - `to` TicketMessageSourceAddress[]: A list of To addresses. To and From are usually present for most channel types.
        - `name` string
        - `address` string
      - `cc` TicketMessageSourceAddress[]: A list of CC addresses. Only present in an email context.
        - `name` string
        - `address` string
      - `bcc` TicketMessageSourceAddress[]: A list of BCC addresses. Only present in an email context.
        - `name` string
        - `address` string
      - `from` TicketMessageSourceAddress
        - `name` string
        - `address` string
      - `extra` unknown
    - `customer` TicketMessageUserOrCustomer, required
      - `id` integer, required
      - `email` string, required
      - `name` string, required
      - `firstname` string, required
      - `lastname` string, required
      - `meta` unknown, required
    - `user` TicketMessageUserOrCustomer, required
      - `id` integer, required
      - `email` string, required
      - `name` string, required
      - `firstname` string, required
      - `lastname` string, required
      - `meta` unknown, required
  - `replied_to` TicketMessageRepliedByOrTo
    - `integration_id` integer, required: ID of the integration which created the message.
    - `message_id` string, required: ID of the message in Gorgias.
    - `created_datetime` string, date-time, required: When the message was created.
    - `body_text` string, required: The full text version of the body of the message, if any.
    - `source` TicketMessageSource, required
      - `type` string, required: Describes a more detailed channel information of how the message was sent/received. Either the slug of a non-legacy channel or one of aircall,api,app,chat,chat-contact-form,chat-offline-capture,contact-form,email,facebook-comment,facebook-message,facebook-messenger,facebook-post,facebook-mention-post,facebook-mention-comment,facebook,facebook-review,facebook-review-comment,form,help-center,helpdesk,instagram-ad-comment,instagram-ad-media,instagram-comment,instagram-mention-comment,instagram-media,instagram-mention-media,instagram,instagram-direct-message,internal-note,ottspott-call,phone,rule,self_service,shopify,sms,system-message,twilio,yotpo-review,yotpo-review-public-comment,yotpo-review-private-comment,twitter-tweet,twitter-quoted-tweet,twitter-mention-tweet,twitter-direct-message,help-center-contact-form,whatsapp-message.
      - `to` TicketMessageSourceAddress[]: A list of To addresses. To and From are usually present for most channel types.
        - `name` string
        - `address` string
      - `cc` TicketMessageSourceAddress[]: A list of CC addresses. Only present in an email context.
        - `name` string
        - `address` string
      - `bcc` TicketMessageSourceAddress[]: A list of BCC addresses. Only present in an email context.
        - `name` string
        - `address` string
      - `from` TicketMessageSourceAddress
        - `name` string
        - `address` string
      - `extra` unknown
    - `customer` TicketMessageUserOrCustomer, required
      - `id` integer, required
      - `email` string, required
      - `name` string, required
      - `firstname` string, required
      - `lastname` string, required
      - `meta` unknown, required
    - `user` TicketMessageUserOrCustomer, required
      - `id` integer, required
      - `email` string, required
      - `name` string, required
      - `firstname` string, required
      - `lastname` string, required
      - `meta` unknown, required

## Other responses

- `412`: The valid `If-Unmodified-Since` precondition failed because the source ticket was merged after the supplied date.

## Changes

- **2026-11-03** `3fdfcb5b6678`: 3 info
  - added the new optional `header` request parameter `If-Unmodified-Since`
  - added the non-success response with the status `412`
  - added the required property `body_url` to the response with the `201` status

[Operation history](https://skmtc.dev/gorgias/apis/gorgias-rest-api/changes/api/tickets/:ticket_id/messages/post.md)

---

[API](https://skmtc.dev/gorgias/apis/gorgias-rest-api.md) - [All operations](https://skmtc.dev/gorgias/apis/gorgias-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gorgias/apis/gorgias-rest-api/revisions/3fdfcb5b6678?raw)