> ## Documentation Index > Fetch the complete documentation index at: https://help.texterchat.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a Message to Chat > Send a session message to an existing chat. Messages can include text, media (image, video, document, audio), interactive buttons, list menus, contact cards and locations. **Required token scopes:** `Send session message` ⚠ **Important:** session messages are subject to WhatsApp's 24-hour window. If the contact has not sent a message in the last 24 hours, WhatsApp blocks session messages and the request fails. In that case, you can only send a **Template Message**. Session messages can only be sent to **existing** chats - sending to a chat that doesn't exist returns an error. All status values, type enums and the ID cheat sheet: [Enums & Common Fields](/api-reference/enums). ## OpenAPI ````yaml api-reference/openapi.json POST /messages/send/{chatId} openapi: 3.1.0 info: title: Texter API V2 version: 2.0.0 description: >- The **Texter API** lets your developers control the Texter platform programmatically: - Manage and send your WhatsApp template messages - Retrieve chats by ID or by various filters - Assign and resolve conversations - Send session messages into active chats - Manage labels - Monitor and resolve channel health issues - Subscribe to real-time webhook events - Manage quick replies (coming soon) For any questions please contact [Texter Support](https://wa.me/972586640430). contact: name: Texter Support url: https://wa.me/972586640430 servers: - url: https://{projectID}.texterchat.com/server/api/v2 description: Your Texter environment. Replace projectID with your project subdomain variables: projectID: default: demo description: >- Your unique project subdomain. If your environment URL is https://demo.texterchat.com, your projectID is "demo" security: - bearerAuth: [] tags: - name: Manage Templates description: >- Create, localize, submit, update, delete and send WhatsApp template messages, and retrieve approved templates for your connected WhatsApp accounts. **Suggested token for this group** - create one API token with the scopes: *Send template messages*, *View template messages*, *Manage WhatsApp templates*, *Manage all chats*, *List all chats* (the last two also cover the Templates Subscriptions group). Each endpoint below also lists the exact scopes it needs. - name: Templates Subscriptions description: >- Manage recipient subscriptions for WhatsApp template messages - unsubscribe or resubscribe recipients, and list unsubscribed users across all channels or for a specific account. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*. Each endpoint below also lists the exact scopes it needs. - name: Messages description: >- Retrieve message history from a chat, or send new session messages - text, media, buttons, lists, contact cards and locations - within the active WhatsApp 24-hour session window. **Suggested token for this group** - scopes: *Send session message*, *View all chats*. Each endpoint below also lists the exact scopes it needs. - name: Chats description: >- Fetch chat details, search conversations, update chat properties, assign or resolve chats, and manage their CRM metadata. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*, *Send session message*. Each endpoint below also lists the exact scopes it needs. - name: Labels description: >- Create and edit labels, assign or remove them from chats, retrieve label data, or delete labels from your inbox. **Suggested token for this group** - scopes: *Manage labels*, *Manage all chats* (needed for managing labels on chats). Each endpoint below also lists the exact scopes it needs. - name: Channels description: >- Monitor and maintain the health of connected messaging channels - retrieve active channel health problems, filter them by severity or account, and mark issues as resolved. **Suggested token for this group** - scopes: *Manage channels*. Each endpoint below also lists the exact scopes it needs. - name: Quick Replies description: >- Manage quick replies - prepared messages agents can send into matching chats with one click. Quick replies marked with `aiQuickReply` client metadata appear as **AI suggestions** in the Texter inbox (see Create Quick Reply for the full flow). **Suggested token for this group** - scopes: *View quick replies*, *Manage quick replies*. Each endpoint below also lists the exact scopes it needs. - name: Files description: >- Generate public access links to media files stored in Texter. **Suggested token for this group** - scopes: *View all files*, *View all chats* (both required). Each endpoint below also lists the exact scopes it needs. - name: Subscribe to Events description: >- Register webhooks for events occurring in your Texter environment. Under the hood this uses **Scenarios** - a workflow automation feature within Texter. To make integration easy, pre-defined templates are provided: import a scenario JSON, plug in your webhook URL and user UID, and the subscription is active. See the **Webhook Events** pages for the payload your URL receives for each event. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*. Each endpoint below also lists the exact scopes it needs. If the provided templates don't satisfy your needs, contact [Texter Support](https://wa.me/972586640430) and we'll gladly help modify any triggers, conditions or actions for your webhook. - name: Scenarios (Advanced) description: >- Full programmatic control over scenarios for advanced automations: create scenarios from scratch, copy them, edit drafts, publish revisions, inspect execution runs, and discover the available building blocks (events, conditions, loaders, actions). For plain webhook subscriptions, the **Subscribe to Events** group with its ready-made templates is the simpler path. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Edit scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*, *View scenarios runs*. Each endpoint below also lists the exact scopes it needs. paths: /messages/send/{chatId}: post: tags: - Messages summary: Send a Message to Chat description: >- Send a session message to an existing chat. Messages can include text, media (image, video, document, audio), interactive buttons, list menus, contact cards and locations. **Required token scopes:** `Send session message` ⚠ **Important:** session messages are subject to WhatsApp's 24-hour window. If the contact has not sent a message in the last 24 hours, WhatsApp blocks session messages and the request fails. In that case, you can only send a **Template Message**. Session messages can only be sent to **existing** chats - sending to a chat that doesn't exist returns an error. All status values, type enums and the ID cheat sheet: [Enums & Common Fields](/api-reference/enums). operationId: send-message parameters: - name: chatId in: path required: true schema: type: string description: >- The unique identifier of the chat. You can obtain this value by using the Search Chats endpoint with the contact's phone number requestBody: required: true content: application/json: schema: type: object description: >- The message contents. `type` selects the message structure; each type has its own required fields. All types also accept the generic `context` and `tmpSendId` options properties: type: type: string enum: - text - media - buttons - list - contacts - location description: Defines the message structure and required fields context: type: string description: >- Reply to a specific message. Use the **provider message ID** (e.g. `wamid...`) from `message.channelInfo.id` tmpSendId: type: string description: A custom client-side ID for tracking the message text: type: string minLength: 1 description: >- The message text. Required for `text`, `buttons` and `list`. For `text` messages: up to 4096 characters (WhatsApp limit) media: type: array minItems: 1 maxItems: 10 description: >- Array of media items. Required for `media`. Each item needs `mediaType` plus either a public `url` (Texter downloads and stores the file) or a `fileId` of a file already stored in Texter items: type: object properties: mediaType: type: string enum: - image - video - document - audio description: Media category url: type: string description: Publicly accessible URL of the media file fileId: type: string description: >- ID of a file already stored in Texter (alternative to `url`) caption: type: string description: >- Caption text. Allowed only when `mediaType` is `image` or `video` filename: type: string description: >- The document's display filename. Allowed only when `mediaType` is `document` required: - mediaType buttons: type: array minItems: 1 maxItems: 3 description: >- Reply buttons. Required for `buttons`. Max 3 buttons (WhatsApp limit) items: type: object properties: title: type: string minLength: 1 description: The text displayed on the button. Max 20 characters payload: type: string minLength: 1 description: Unique ID delivered back in the postback when clicked required: - title - payload list: type: object description: >- List menu configuration. Required for `list`. Max 10 rows total across all sections (WhatsApp limit) properties: button: type: string minLength: 1 description: >- Title of the button that opens the list view. Max 20 characters sections: type: array minItems: 1 items: type: object properties: title: type: string minLength: 1 description: >- Section header title (required; not shown to the recipient when there is only one section). Max 24 characters rows: type: array minItems: 1 items: type: object properties: title: type: string minLength: 1 description: >- The main text of the row option. Max 20 characters payload: type: string minLength: 1 description: >- Unique ID delivered back in the postback. Must be unique across all rows description: type: string description: >- Optional context text displayed below the row title. Max 72 characters required: - title - payload required: - title - rows required: - button - sections contacts: type: array minItems: 1 description: Contact cards to share. Required for `contacts` items: type: object properties: name: type: object properties: formatted_name: type: string description: Full name of the contact first_name: type: string last_name: type: string required: - formatted_name phones: type: array items: type: object properties: phone: type: string type: type: string description: e.g. `MOBILE`, `WORK` required: - phone emails: type: array items: type: object properties: email: type: string type: type: string required: - email org: type: object properties: company: type: string department: type: string title: type: string description: Job title urls: type: array items: type: object properties: url: type: string required: - url required: - name location: type: object description: Location to share. Required for `location` properties: latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 name: type: string description: Location name shown under the pin address: type: string url: type: string required: - latitude - longitude required: - type examples: Text message: value: type: text text: Hey there! Track with your own ID: value: type: text text: Your order is on its way! tmpSendId: crm-evt-545134 Reply to a specific message: value: type: text text: איך אפשר לעזור? context: >- wamid.HBgMOTcyNTI3NzYwOTg5FQIAERgSQUY1NTUzQ0RFNzFGNTBEOTc1AA== Document attachment: value: type: media media: - mediaType: document url: >- https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf filename: Dummy PDF Multiple files: value: type: media media: - mediaType: image url: https://picsum.photos/536/354 caption: image caption - mediaType: video url: >- http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4 Re-send a stored file by fileId: value: type: media media: - mediaType: image fileId: 6900c1eac29d42708adac92f Buttons menu: value: type: buttons text: Please select one of the options below buttons: - title: option 1 payload: option_1 - title: option 2 payload: option_2 - title: option 3 payload: option_3 List menu (single section): value: type: list text: Which representative would you like to be forwarded to? list: button: All Agents sections: - title: Will be omitted rows: - title: Ziv payload: ziv@texter.com description: AI Engineer - title: Paz payload: paz@texter.com description: Product Manager - title: Noam payload: noam@texter.com List menu (multiple sections): value: type: list text: Welcome to support! How can we assist you today? list: button: View Menu sections: - title: Order Issues rows: - title: Track my order payload: action_track_order description: Check delivery status for recent items - title: Report missing item payload: action_missing_item description: Start a claim for incomplete delivery - title: Account Services rows: - title: Reset Password payload: action_reset_pw - title: Chat with Agent payload: action_human_handoff description: 'Wait time: ~2 mins' Contact card: value: type: contacts contacts: - name: formatted_name: John Doe first_name: John last_name: Doe phones: - phone: '+972521234567' type: MOBILE emails: - email: john@example.com type: WORK org: company: Texter title: Account Manager Location: value: type: location location: latitude: 32.0701 longitude: 34.7935 name: Head Office address: Tel Aviv, Israel url: https://maps.app.goo.gl/example responses: '200': description: >- A confirmation object containing the sent message(s). Field-by-field reference: [The Message object](/api-reference/objects/message) content: application/json: schema: type: object properties: success: type: boolean example: true messages: type: array items: $ref: '#/components/schemas/Message' example: success: true messages: - _id: 6909177d962e17ab3033fa2a chatChannelInfo: name: whatsapp id: '972521234567' accountId: '972509876543' channelInfo: id: >- wamid.HBgMOTcyNTI3NzYwOTg5FQIAERgSRDI2RjUwMkFFQTNEQjE0MEVBAA== direction: outgoing parent_chat: 67a87067aeedqdee1271ck4d status: 0 statusHistory: - status: 0 timestamp: 1762203517914 text: Hey there! timestamp: 1762203517914 type: text updatedAt: '2025-11-03T20:58:37.936Z' '400': description: >- Validation error, unsupported content for the channel, or media download failure content: application/json: schema: $ref: '#/components/schemas/SendErrorResponse' example: error: 'media[1]: File caption is unsupported for document media type!' success: false '401': description: Missing or invalid token, or missing required scope '404': description: Chat not found - session messages can only be sent to existing chats content: application/json: schema: $ref: '#/components/schemas/SendErrorResponse' example: error: >- Existing chat not found. Session message could be sent only to existing chat. success: false components: schemas: Message: type: object description: >- A message within a chat. Messages come in two variants: **regular messages** (actual conversation) and **system messages** (`systemMessage: true` - routing/assignment records that only carry `newChatStatus`, `agent`, `assignedToAgent`, `assignedToDepartment` and timestamps; they have no `direction`, `status`, content or reactions) properties: _id: type: string description: Unique message ID in Texter example: 69062b15962e17ab3033f886 systemMessage: type: boolean description: >- Marks a system/control message instead of a normal chat bubble. `true` messages describe routing / assignment / status changes and omit most regular-message fields type: type: string enum: - text - media - contacts - location - buttons - list - postback - special description: The content type of the message text: type: string description: >- Human-readable body text. Present on most `text`, `buttons`, `list` and `special` messages buttons: type: array description: >- Interactive reply buttons that were sent. Only when `type` is `buttons` items: type: object properties: title: type: string payload: type: string list: type: object description: WhatsApp "list picker" that was sent. Only when `type` is `list` properties: button: type: string sections: type: array items: type: object properties: title: type: string rows: type: array items: type: object properties: title: type: string payload: type: string description: type: string postback: type: object description: >- Which list item / button the contact chose. Only when `type` is `postback` (incoming) properties: payload: type: string title: type: string description: type: string media: type: array description: Array of media items in this message. Only when `type` is `media` items: $ref: '#/components/schemas/MediaItem' location: type: object description: Shared location data. Only when `type` is `location` properties: latitude: type: number longitude: type: number name: type: string address: type: string url: type: string contacts: type: array description: Shared contact cards. Only when `type` is `contacts` items: $ref: '#/components/schemas/ContactCard' special: type: object additionalProperties: true description: >- Channel-specific or structured content. Only when `type` is `special`. Known flags: `redacted: true` (contents redacted as sensitive), `deleted: { previousType, timestamp }` (contents removed by scheduled deletion - explains "empty" messages), `isEchoMessage: true` (outgoing message sent from another client, not Texter), `isHistoryMessage: true`, `isStatusMessage: true`, `unsupportedByProvider: true`, plus channel-specific keys (`whatsapp`, `messenger`, `instagram`, `email`) such as template send data metadata: type: object description: Extra metadata about this message properties: triggeredBot: type: boolean description: Whether this incoming message triggered automation/bot logic botMsgInfo: type: object description: Which bot node generated this outgoing message properties: identifier: type: string version: type: number nodeName: type: string hideSummary: type: boolean bulkSendId: type: string description: Bulk / campaign batch ID for this message whatsappTemplate: type: object description: >- Structured template send data for outgoing WhatsApp template messages properties: name: type: string description: Template name localization: type: object additionalProperties: true description: The localization that was sent contents: type: object additionalProperties: true description: The resolved send contents (header, body values, buttons) additionalProperties: true chatChannelInfo: allOf: - $ref: '#/components/schemas/ChannelInfo' description: Which channel account / contact this message belongs to channelInfo: type: object description: >- Provider-side message identifier - use it to correlate with WhatsApp provider / Meta logs. Note: on system messages (`systemMessage: true`) the `id` is an internal placeholder with no provider meaning properties: id: type: string example: wamid.HBgMOTcyNTI3NzYwOTg5FQIAERgS... metadata: type: object additionalProperties: true direction: type: string enum: - incoming - outgoing description: Logical direction of the message. Regular messages only status: $ref: '#/components/schemas/MessageStatus' statusHistory: type: array description: Timeline of delivery/read states for this message items: type: object properties: status: $ref: '#/components/schemas/MessageStatus' timestamp: type: number description: Epoch milliseconds reactions: type: array items: type: string description: Current emoji reactions on the message reactionsHistory: type: array description: Timeline of reaction add/remove events items: type: object properties: timestamp: type: number description: Epoch milliseconds reaction: type: string description: The emoji, when added removed: type: boolean description: '`true` when this event removed the reaction' timestamp: type: number description: When the message was created (epoch **milliseconds**) updatedAt: type: string format: date-time description: >- Last time this message was updated (e.g. when delivery status changes) parent_chat: type: string description: The chat ID this message belongs to agent: type: string description: Which agent or bot sent this message - `"Bot"` or an agent UID assignedToAgent: type: string description: >- Which agent the chat was assigned to at this moment. Only on system messages assignedToDepartment: type: string description: >- Which department the chat was assigned to. Only on some system messages newChatStatus: allOf: - $ref: '#/components/schemas/ChatStatus' description: >- New chat status after this routing/system event. Only on system messages botSessionId: type: string description: Bot session / flow instance ID tied to this message hideSummary: type: boolean description: Whether this message should be hidden from summaries tmpSendId: description: >- Client-generated ID to match a send request to the stored message. String or number oneOf: - type: string - type: number errorReason: type: string description: >- Reason the send failed (provider error, throttling, 24h window, etc.). Only present if delivery failed context: type: object additionalProperties: true description: >- The message this message replies to. In API read/send responses this is **populated into a full Message object** (same schema, recursive). In raw webhook payloads it may be only the provider reference `{ id }` of the replied-to message forwarded: type: boolean description: Whether WhatsApp marked the message as forwarded sensitive: type: boolean description: >- Whether the content is marked sensitive and should be redacted in some views scheduledDeletion: type: object description: >- Present when the message is scheduled for deletion by data-retention rules properties: timestamp: type: number description: Planned deletion time (epoch ms) type: type: string enum: - full - contents - media description: What gets deleted setManuallyByUid: type: string description: Agent UID, when the deletion was scheduled manually incoming: type: boolean deprecated: true description: Deprecated - use `direction` instead outgoing: type: boolean deprecated: true description: Deprecated - use `direction` instead received: type: number deprecated: true description: Deprecated (epoch ms) - use `timestamp` instead botMsgInfo: type: object deprecated: true additionalProperties: true description: Deprecated - use `metadata.botMsgInfo` instead bulkSendId: type: string deprecated: true description: Deprecated - use `metadata.bulkSendId` instead providerMessageId: type: string deprecated: true description: Deprecated - use `channelInfo.id` instead messageId: type: string deprecated: true description: Deprecated - use `_id` instead templateId: type: string deprecated: true description: Deprecated - use `metadata.whatsappTemplate` instead templateMessage: type: boolean deprecated: true description: Deprecated - use `metadata.whatsappTemplate` instead templateMessageData: type: object deprecated: true additionalProperties: true description: Deprecated - use `metadata.whatsappTemplate` instead parameters: type: array deprecated: true items: type: string description: Deprecated - use `metadata.whatsappTemplate` instead SendErrorResponse: type: object properties: error: type: string description: Human-readable error message success: type: boolean example: false required: - error MediaItem: type: object description: A media file attached to a message properties: mediaType: type: string enum: - image - video - document - audio - sticker description: The kind of file in this media item fileId: type: string description: >- Internal file ID in Texter storage. Use with Generate Public Media URL to download example: 6900c1eac29d42708adac92f previewId: type: string description: Internal preview/thumbnail file ID filename: type: string description: Original filename from the sender device example: offer_october_2025.pdf contentType: type: string description: MIME type example: application/pdf caption: type: string description: >- Optional caption text attached to the media. Relevant when mediaType is `image` or `video` metadata: type: object additionalProperties: true description: Channel / provider metadata for this attachment example: frequentlyForwarded: false scanned: type: boolean description: Whether the file has been scanned for threats deleted: type: object description: >- Present when the media file was removed by scheduled deletion (the message itself remains). The `fileId` no longer resolves properties: timestamp: type: number description: When the file was deleted (epoch ms) url: type: string deprecated: true description: Deprecated - use the `fileId` download flow instead ContactCard: type: object description: A shared contact card (vCard-style) properties: name: type: object properties: formatted_name: type: string description: Full name of the contact first_name: type: string last_name: type: string middle_name: type: string prefix: type: string description: e.g. Mr., Ms., Dr. suffix: type: string description: e.g. Jr., Sr., III required: - formatted_name phones: type: array items: type: object properties: phone: type: string type: type: string description: e.g. MOBILE, WORK required: - phone emails: type: array items: type: object properties: email: type: string type: type: string required: - email urls: type: array items: type: object properties: url: type: string required: - url addresses: type: array items: type: object properties: street: type: string city: type: string state: type: string zip: type: string country: type: string country_code: type: string description: Two-letter country code type: type: string description: HOME or WORK org: type: object properties: company: type: string department: type: string title: type: string description: Job title birthday: type: string description: YYYY-MM-DD formatted string ChannelInfo: type: object description: Channel that an entity belongs to properties: name: type: string enum: - whatsapp - messenger - instagram - website_chat - email - sms description: Messaging channel type accountId: type: string description: >- The business account ID connected to Texter. For WhatsApp this is the business phone number example: '972586640430' id: type: string description: >- The contact's ID on the channel. For WhatsApp this is the contact's phone number example: '972521234567' metadata: type: object additionalProperties: true description: Channel-specific metadata, when present MessageStatus: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 description: >- Message delivery status: `0` = Sent, `1` = Accepted by provider, `2` = Delivered, `3` = Seen, `4` = Failed, `5` = Channel Failed, `6` = Deleted ChatStatus: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: >- Chat status: `0` = BOT (handled by bot), `1` = PENDING (waiting for an agent), `2` = ASSIGNED (shown as "Taken" in Texter), `3` = RESOLVED, `4` = BULK securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token generated in Texter: gear icon → Developers → API Tokens. When creating a token, assign it the scopes required by the endpoints you plan to call - each endpoint lists its required scopes. ````