Create Message
gorgias_create_messageCreate a new message on an existing ticket to send to a customer, import an already-sent message, or add an internal note.
Instructions
POST /api/tickets/{ticket_id}/messages — Create a new message on an existing ticket. Supports three use cases: (1) Send to customer — omit sent_datetime, Gorgias sends asynchronously; (2) Import already-sent message — provide sent_datetime; (3) Internal note — set channel to 'internal-note' and public to false.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| via | Yes | How the message was received or sent from Gorgias (e.g. 'api', 'email', 'helpdesk') | |
| meta | No | Custom structured metadata. Reserved keys: current_page, relevant_content_indexes, is_quick_reply, campaigns, campaigns_id, self_service_flow. | |
| action | No | Controls behavior when an external send action fails: 'force' bypasses the failure, 'retry' retries it, 'cancel' cancels it | |
| macros | No | Macros to apply. Each item must have an id field (integer > 0). Example: [{"id": 42}] | |
| public | No | Whether the message is visible to customers. Set to false for internal notes (default: true) | |
| sender | No | The message originator (user or customer). Object with optional fields: id (integer >= 0), email (string <= 320 chars), name, external_id, channels (array of {type, address}), language, timezone, meta, note. Example: {"id": 93, "email": "agent@example.com"} | |
| source | No | Routing details for the message. Object with fields: type (TicketMessageSourceType string), from (object with address and name), to (array of address objects), cc (array), bcc (array), extra. Example: {"type": "email", "from": {"address": "sender@example.com", "name": "Sender"}, "to": [{"address": "receiver@example.com", "name": "Receiver"}]} | |
| channel | Yes | Channel used to send the message. Use 'internal-note' for agent-only notes. | |
| headers | No | Message headers as key-value pairs (primarily for email). Example: {"X-Custom-Header": "value"} | |
| subject | No | Message subject line (primarily for email) | |
| receiver | No | The primary message recipient (user or customer). Optional for internal notes. Same schema as sender: id, email, name, external_id, channels, language, timezone, meta, note. Example: {"id": 8, "email": "customer@example.com"} | |
| body_html | No | HTML-formatted message body | |
| body_text | No | Plain-text message body | |
| ticket_id | Yes | The ID of the ticket to add the message to | |
| from_agent | Yes | true if sent by your company (agent), false if sent by a customer | |
| message_id | No | ID of the message on the originating external service (e.g. email Message-ID header) | |
| attachments | No | Files to attach. Each item: url (required URI), name (required), content_type (required MIME type), size (bytes), public (boolean, default true), extra. | |
| external_id | No | ID of the message in a foreign system (max 255 chars). Not used by Gorgias. | |
| mention_ids | No | List of User IDs to mention in an internal note. Only valid for internal-note messages. | |
| sent_datetime | No | ISO 8601 datetime when the message was sent. If omitted, Gorgias will send it and populate this field. Providing a value imports the message as already-sent. | |
| stripped_html | No | HTML body with signatures and prior replies removed | |
| stripped_text | No | Plain-text body with signatures and prior replies removed | |
| integration_id | No | ID of the integration used to send the message (must be > 0) | |
| failed_datetime | No | ISO 8601 datetime when the send attempt failed | |
| opened_datetime | No | ISO 8601 datetime when the recipient viewed the message | |
| created_datetime | No | ISO 8601 datetime when the message was created | |
| deleted_datetime | No | ISO 8601 datetime when the message was deleted | |
| last_sending_error | No | Details of a known sending error. Object with an 'error' string field describing the transmission error. | |
| stripped_signature | No | Extracted signature portion of the message |