> ## Documentation Index > Fetch the complete documentation index at: https://docs.shortext.ny-corp.io/llms.txt > Use this file to discover all available pages before exploring further. # Submit an inbound message > Submit a message written by one of **your** users and let the Shortext agent answer it. **Reply modes** - `sync`: the request waits for the agent reply (max ~25 s) and returns it in `body.replies`. On timeout `body.status` is `pending` and the reply is delivered to your webhook. - `async`: the request returns immediately with `accepted`; replies are delivered to your webhook. **Idempotency**: `message.id` is your own message id. Sending the same id again returns `duplicate` with the original message, without a second reply. **Webhook**: replies (async, sync timeout, human agent answers) are POSTed to the endpoint webhook with the `ShortextWebhookEvent` body, signed with `X-Shortext-Signature: sha256=hex(hmac_sha256(secret, "{X-Shortext-Timestamp}.{raw_body}"))`. ## OpenAPI ````yaml /api-reference/openapi.json post /messages/inbound openapi: 3.1.0 info: title: Shortext API description: This is my API version: '1.0' servers: - url: https://shortext.ny-corp.io/api - url: https://whatsapp-gateway.test/api security: [] tags: - name: Agents description: Agents - name: Business - Manager description: Business - Manager - name: Messages description: Messages - name: Tickets description: Tickets - name: Knowledge description: Knowledge - name: health description: health paths: /messages/inbound: post: tags: - Messages summary: Submit an inbound message description: >- Submit a message written by one of **your** users and let the Shortext agent answer it. **Reply modes** - `sync`: the request waits for the agent reply (max ~25 s) and returns it in `body.replies`. On timeout `body.status` is `pending` and the reply is delivered to your webhook. - `async`: the request returns immediately with `accepted`; replies are delivered to your webhook. **Idempotency**: `message.id` is your own message id. Sending the same id again returns `duplicate` with the original message, without a second reply. **Webhook**: replies (async, sync timeout, human agent answers) are POSTed to the endpoint webhook with the `ShortextWebhookEvent` body, signed with `X-Shortext-Signature: sha256=hex(hmac_sha256(secret, "{X-Shortext-Timestamp}.{raw_body}"))`. operationId: receiveInboundMessage requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InboundMessageRequest' responses: '200': description: Message stored. See body.status for the reply outcome. content: application/json: schema: $ref: '#/components/schemas/InboundMessageResponse' security: - bearerAuth: [] components: schemas: InboundMessageRequest: required: - channel - to - contact - message properties: channel: description: Only native channels accept inbound messages type: string enum: - shortext example: shortext to: description: Endpoint ID shown in the Shortext dashboard type: string example: ste_8k2m4q9x1v7c3n5b6z0p2r4t contact: required: - identifier properties: identifier: description: Your own user id. Unique per endpoint. type: string maxLength: 150 example: user-42 profile: properties: lastname: type: string maxLength: 250 example: Awa firstname: type: string maxLength: 250 email: type: string format: email preferred_language: type: string enum: - en - fr - es - de type: object type: object message: required: - id - type - content properties: id: description: Your own message id, used for idempotency type: string maxLength: 100 example: client-msg-001 type: type: string enum: - text example: text content: $ref: '#/components/schemas/TextMessageContent' metadata: description: Free context stored with the message (page, cart...) type: object example: page: /checkout type: object reply_mode: description: Defaults to the endpoint setting type: string enum: - sync - async example: sync type: object InboundMessageResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - properties: body: $ref: '#/components/schemas/InboundMessageResult' type: object TextMessageContent: title: Text Message description: >- WhatsApp allow text message only when there is already an open session between the contact and the business number required: - text properties: text: description: 'for embedded url please use this format ex: https://shortext.io' type: string maxLength: 4096 example: Ceci est un message texte. preview_url: type: boolean default: true example: true type: object ApiResponse: description: >- Standard lite-api envelope. Every endpoint answers with it; only `body` changes. required: - success - code - message properties: success: type: boolean example: true code: $ref: '#/components/schemas/ResponseCode' message: type: string example: Request success body: description: Endpoint-specific payload, null on most errors type: - object - 'null' token: description: Present only on authentication routes type: - string - 'null' trace_id: description: Present only when success=false. Give it to support. type: - string - 'null' type: object InboundMessageResult: properties: status: description: >- completed: replies included | pending: sync timeout, reply via webhook | accepted: async | no_auto_reply: stored without automatic reply (human handover, balance, no agent) | duplicate: message.id already received type: string enum: - completed - pending - accepted - no_auto_reply - duplicate message: $ref: '#/components/schemas/MessageV2' replies: type: array items: $ref: '#/components/schemas/MessageV2' type: object ResponseCode: description: >- Standard response codes defined by the system / Codes de réponse standard définis par le système. type: integer enum: - -1 - -2 - -3 - -4 - -5 - 1000 - -1001 - -1002 - -1003 - -1004 - -1005 - -1006 - -1007 - -1008 - -1009 - -1010 - -1100 - -1101 - -1102 - -1103 - 1104 - -1105 example: 1000 MessageV2: description: >- A message as exposed by the API v2 and the webhooks. Same grammar as the requests. properties: id: description: Shortext message id type: string example: msg.Xk29aB conversation_id: type: string example: cnv.7Hq2Lm direction: type: string enum: - inbound - outbound channel: type: string example: shortext channel_id: description: Channel identifier (the `to` / `from` value) type: string example: ste_8k2m4q9x1v7c3n5b6z0p2r4t contact: properties: identifier: description: Your own user id on the shortext channel type: string example: user-42 identifier_type: type: string example: external_id profile: properties: lastname: type: string example: Awa firstname: type: string email: type: string preferred_language: type: string example: fr type: object country: description: Only when known type: - object - 'null' type: object message: properties: id: description: Your message.id for inbound messages, Shortext id otherwise type: string example: client-msg-001 type: type: string example: text content: description: Same shape as message.content in requests type: object example: text: Oui, nous livrons à Douala. type: object status: type: string example: sent created_at: type: string format: date-time type: object securitySchemes: bearerAuth: type: http description: >- Company API token (Laravel Sanctum), sent as "Authorization: Bearer " scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.