> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Send message

> Same PIV1 contract as other channels: `from` (Chat App), `to` (conversation id), `type`, and `payload`. With API Key, `senderExternalUserId` is required. Scope: **chat:messages:send**. 1 CHAT_MESSAGE credit.



## OpenAPI

````yaml /en/chat-api/api-reference/openapi-chat.json post /v1/chat/messages
openapi: 3.0.3
info:
  title: Notifique Chat API
  description: >-
    In-app chat: apps, users, JWT, conversations, and messages. Authenticate
    with `Authorization: Bearer sk_live_...` (backend) or a user JWT. Do not
    send `x-workspace-id`.
  version: 1.0.0
servers:
  - url: https://api.notifique.dev
    description: Produção
security:
  - ntfChatBearerAuth: []
  - ntfChatApiKeyHeader: []
tags:
  - name: Chat Apps
    description: CRUD de Chat Apps e rotação do signing secret
  - name: Chat Users
    description: Usuários, JWT e agentes
  - name: Chat Conversations
    description: Conversas 1:1, grupos e membros
  - name: Chat Messages
    description: Envio, listagem e exclusão
  - name: Chat Blocks
    description: Blocks between users of the same Chat App
paths:
  /v1/chat/messages:
    post:
      tags:
        - Chat Messages
      summary: Send message
      description: >-
        Same PIV1 contract as other channels: `from` (Chat App), `to`
        (conversation id), `type`, and `payload`. With API Key,
        `senderExternalUserId` is required. Scope: **chat:messages:send**. 1
        CHAT_MESSAGE credit.
      operationId: ntfChat_postV1ChatMessages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NtfChat_SendMessageRequest'
            examples:
              text:
                summary: Text
                value:
                  from: clxxapp...
                  to:
                    - cnv_xxxxx
                  type: text
                  payload:
                    message: Hi Alice, your order is out for delivery.
                  senderExternalUserId: agent:clxxuser...
                  clientMessageId: msg_text_001
              image:
                summary: Image
                value:
                  from: clxxapp...
                  to:
                    - cnv_xxxxx
                  type: image
                  payload:
                    mediaUrl: https://cdn.yoursite.com/receipt.png
                    message: Delivery receipt
                  senderExternalUserId: user_alice
              audio:
                summary: Audio
                value:
                  from: clxxapp...
                  to:
                    - cnv_xxxxx
                  type: audio
                  payload:
                    mediaUrl: https://cdn.yoursite.com/note.ogg
                  senderExternalUserId: user_bob
              file:
                summary: File
                value:
                  from: clxxapp...
                  to:
                    - cnv_xxxxx
                  type: file
                  payload:
                    mediaUrl: https://cdn.yoursite.com/contract.pdf
                    message: Signed contract
                  senderExternalUserId: agent:clxxuser...
              jwt:
                summary: Member JWT
                value:
                  to:
                    - cnv_xxxxx
                  type: text
                  payload:
                    message: I'm here
              reply:
                summary: Reply
                value:
                  from: clxxapp...
                  to:
                    - cnv_xxxxx
                  type: text
                  payload:
                    message: Sounds good, thanks
                  senderExternalUserId: agent:clxxuser...
                  replyToId: clxxmsg...
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/NtfChat_Message'
                      - type: array
                        items:
                          $ref: '#/components/schemas/NtfChat_Message'
                  idempotent:
                    type: boolean
        '401':
          description: Missing or invalid API Key or JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfChat_ErrorResponse'
        '402':
          description: Workspace blocked or insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfChat_ErrorResponse'
        '403':
          description: Missing scope, origin not allowed, or JWT without permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfChat_ErrorResponse'
components:
  schemas:
    NtfChat_SendMessageRequest:
      type: object
      properties:
        from:
          type: string
          description: Chat App id. If set, it must match the conversation.
          example: clxxapp...
        to:
          oneOf:
            - type: string
              example: cnv_xxxxx
            - type: array
              items:
                type: string
              example:
                - cnv_xxxxx
          description: Conversation id (string or list).
        type:
          type: string
          enum:
            - text
            - image
            - audio
            - file
          example: text
        payload:
          type: object
          description: PIV1 content. Text in message; media in mediaUrl (HTTPS).
          properties:
            message:
              type: string
              example: Olá
            caption:
              type: string
            mediaUrl:
              type: string
              format: uri
              example: https://cdn.example.com/a.png
            replyToId:
              type: string
            clientMessageId:
              type: string
        senderExternalUserId:
          type: string
          description: Required with API Key. externalUserId of a USER or AGENT.
          example: user_alice
        clientMessageId:
          type: string
          example: msg_001
        replyToId:
          type: string
        body:
          type: string
          description: Legacy. Prefer payload.message.
        mediaUrl:
          type: string
          description: Legacy. Prefer payload.mediaUrl.
    NtfChat_Message:
      type: object
      properties:
        id:
          type: string
          example: clxxmsg...
        conversationId:
          type: string
          example: cnv_xxxxx
        type:
          type: string
          enum:
            - TEXT
            - IMAGE
            - AUDIO
            - FILE
          example: TEXT
        body:
          type: string
          example: Oi, Alice
        createdAt:
          type: string
          format: date-time
        senderId:
          type: string
        mediaUrl:
          type: string
          nullable: true
          example: null
        replyToId:
          type: string
          nullable: true
        clientMessageId:
          type: string
          nullable: true
          example: msg_text_001
        deletedAt:
          type: string
          format: date-time
          nullable: true
        sender:
          type: object
          properties:
            id:
              type: string
            externalUserId:
              type: string
              example: user_alice
            name:
              type: string
              nullable: true
            kind:
              type: string
              enum:
                - USER
                - AGENT
              example: USER
    NtfChat_ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        code:
          type: string
        message:
          type: string
  securitySchemes:
    ntfChatBearerAuth:
      type: http
      scheme: bearer
      description: API Key `sk_live_…` / `sk_test_…` ou JWT do usuário do chat (`eyJ…`).
    ntfChatApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````