> ## Documentation Index > Fetch the complete documentation index at: https://docs.watahub.dev/llms.txt > Use this file to discover all available pages before exploring further. # Send a WhatsApp message > Send a WhatsApp message ## OpenAPI ````yaml openapi.json POST /v1/messages openapi: 3.1.0 info: title: Watahub API version: 0.2.0 description: >- Tenant API of Watahub, the multi-tenant WhatsApp Cloud API gateway. Authenticate every request with your API key as `Authorization: Bearer ` or `X-API-Key: `. - Shapes the gateway owns are closed: no other field appears. - Records that come from Meta are open: documented fields are listed and any other field Meta adds is passed through. - The `/vN.N` proxy passes Meta's body and status through untouched; the version in the path is accepted and ignored. servers: - url: https://cloud.watahub.dev security: - bearerApiKey: [] - headerApiKey: [] tags: - name: Messages - name: Media - name: Templates - name: Graph-compatible proxy description: >- Drop-in for Meta's Graph API on three routes. Meta's response is returned as is. - name: Phones description: Phones - name: Conversations description: Conversations - name: Connect description: Connect - name: Customers description: Customers - name: Webhooks description: Webhooks - name: Logs description: Logs - name: Health description: Health - name: Message templates description: >- Templates cached by the gateway per WABA; synced from Meta and required by broadcasts. - name: Broadcasts description: >- Send one approved template to up to 500 recipients; sending is queued and drained in the background. paths: /v1/messages: post: tags: - Messages summary: Send a WhatsApp message description: >- The core translates the body into Meta's `/messages` call and answers with its own shape, not Meta's. Meta's `wa_id` and `message_status` are not returned. A 5XX `MetaError` on a send has category `unknown_outcome`: the message may have been sent. operationId: sendMessage requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessage' responses: '200': $ref: '#/components/responses/MessageSent' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' components: schemas: SendMessage: type: object required: - to - kind description: >- The object matching `kind` is required (`media` for image, audio, video, document and sticker). properties: to: type: string minLength: 1 maxLength: 135 description: Recipient phone number or business-scoped user ID. phoneNumberId: type: string pattern: ^\d{1,32}$ kind: type: string enum: - text - template - image - audio - video - document - reaction - interactive - location - contacts - sticker text: type: object required: - body properties: body: type: string minLength: 1 maxLength: 4096 template: type: object required: - name - language properties: name: type: string maxLength: 512 language: type: object required: - code properties: code: type: string minLength: 2 maxLength: 16 components: type: array items: type: object additionalProperties: true media: type: object description: >- Provide id or link. Audio: no caption/filename; voice only for audio. Video: no filename. properties: id: type: string pattern: ^\d{1,32}$ link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 voice: type: boolean reaction: type: object required: - messageId - emoji properties: messageId: type: string maxLength: 256 emoji: type: string maxLength: 16 location: type: object required: - latitude - longitude properties: latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 name: type: string maxLength: 256 address: type: string maxLength: 512 contacts: type: array minItems: 1 maxItems: 10 items: type: object additionalProperties: true description: WhatsApp contact card; name.formatted_name required. interactive: type: object additionalProperties: true description: >- Meta interactive object. Validated for type flow, location_request_message, cta_url, product, product_list and order_details. replyToMessageId: type: string maxLength: 256 SendMessageResult: type: object additionalProperties: false required: - success - messageId - recipient - phoneNumberId properties: success: const: true messageId: type: string description: Meta's `messages[0].id` (the wamid). Empty when Meta returns none. recipient: type: string description: >- Meta's `contacts[0].input`; otherwise the phone number sent, without `+`, or the BSUID. phoneNumberId: type: string description: The number that sent the message. GatewayError: type: object description: >- An error the gateway or the core answers itself. `error` is a stable English message for developers. additionalProperties: false required: - error properties: error: type: string fields: type: array items: type: string description: 'With 400 `Invalid fields`: the paths of the rejected fields.' requestId: type: string description: 'With 500 `Operation unavailable`: the ID to quote to support.' ValidationError: type: object description: The core rejected a value of the body, path, header or query. additionalProperties: false required: - error - details properties: error: const: Validation failed details: type: object description: Messages by field name. additionalProperties: type: array items: type: string MetaError: type: object description: >- Meta failed a `/v1` call. With Meta's error: `code`, its `subcode`, `type` on sends, and the core's classification. When Meta could not be reached or answered something unusable, only `message`, plus the `unknown_outcome` classification on sends. additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - message properties: message: type: string code: type: integer description: Meta's error code; Meta's HTTP status when Meta gave none. subcode: type: integer description: Meta's `error_subcode`. type: type: string description: Meta's error type. Only on message sends. category: type: string enum: - auth - billing - rate_limit - meta_server - unknown - unknown_outcome retryable: type: boolean action: type: string description: What to do next, in English. responses: MessageSent: description: Meta accepted the message. content: application/json: schema: $ref: '#/components/schemas/SendMessageResult' ClientError: description: >- Rejected by the gateway (`GatewayError`), by the core's validation (`ValidationError`, 422) or by Meta (`MetaError`, with Meta's status). content: application/json: schema: anyOf: - $ref: '#/components/schemas/GatewayError' - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/MetaError' ServerError: description: >- `GatewayError` for a gateway failure (500 with `requestId`, 503 for missing configuration); `MetaError` for a Meta 5XX, an unreachable Meta (502) or a Meta timeout (504). content: application/json: schema: anyOf: - $ref: '#/components/schemas/GatewayError' - $ref: '#/components/schemas/MetaError' securitySchemes: bearerApiKey: type: http scheme: bearer description: Tenant API key. headerApiKey: type: apiKey in: header name: X-API-Key description: Tenant API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.