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

# Envía un mensaje de WhatsApp (texto, plantilla, imagen o documento)



## OpenAPI

````yaml https://api-v2.sofiachat.com/api/v1/openapi.json post /messages
openapi: 3.0.0
info:
  title: Sofia Chat API
  description: >-
    API externa de Sofia Chat para integraciones servidor-a-servidor.


    ## Autenticación

    Todas las peticiones requieren el header `X-API-Key` con una API key válida
    de la organización.


    ```

    X-API-Key: <tu_api_key>

    ```


    ## Scopes

    Cada API key tiene scopes que autorizan las operaciones:

    - `read`: acceso de lectura (endpoints GET).

    - `write`: acceso de escritura (endpoints POST, PATCH y DELETE).


    ## Rate limit

    El límite se aplica por API key (no por IP):

    - 300 peticiones/min en endpoints de lectura.

    - 60 peticiones/min en endpoints de escritura (`write`).


    Al superarlo la API responde `429 Too Many Requests`.
  version: '1.0'
  contact: {}
servers:
  - url: https://api-v2.sofiachat.com/api/v1
security: []
tags: []
paths:
  /messages:
    post:
      tags:
        - Mensajes
      summary: Envía un mensaje de WhatsApp (texto, plantilla, imagen o documento)
      operationId: MessagesController_send
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageDto'
            examples:
              template:
                summary: Plantilla (template)
                description: >-
                  Envía una plantilla aprobada en Meta con sus parámetros de
                  body.
                value:
                  channelId: 12
                  to: +521 55 1234 5678
                  type: template
                  template:
                    name: recordatorio_cita
                    language: es_MX
                    parameters:
                      nombre: Juan
                      fecha: 3 de agosto
              text:
                summary: Texto (text)
                description: >-
                  Mensaje de texto libre a un contacto existente (dentro de la
                  ventana de 24h).
                value:
                  channelId: 12
                  contactId: 345
                  type: text
                  text: Hola, ¿en qué podemos ayudarte?
              image:
                summary: Imagen (image)
                description: Imagen por URL con caption opcional en el campo text.
                value:
                  channelId: 12
                  to: +521 55 1234 5678
                  type: image
                  mediaUrl: https://cdn.sofiachat.com/media/promo-agosto.jpg
                  text: Nuestra promoción de agosto
      responses:
        '201':
          description: ''
      security:
        - api-key: []
components:
  schemas:
    CreateMessageDto:
      type: object
      properties:
        channelId:
          type: number
          description: ID de la integración (canal) de WhatsApp de la organización
          example: 12
        to:
          type: string
          description: >-
            Teléfono destino (se normaliza a E.164). Exactamente uno de
            to/contactId/chatUserId.
          example: +521 55 1234 5678
        contactId:
          type: number
          description: ID de contacto de la organización
          example: 345
        chatUserId:
          type: number
          description: ID de ChatUser existente
          example: 678
        type:
          type: string
          enum:
            - text
            - template
            - image
            - document
          description: Tipo de mensaje a enviar
          example: text
        text:
          type: string
          description: Texto del mensaje (type=text) o caption (image/document)
          example: Hola, ¿en qué podemos ayudarte?
        template:
          description: Payload de la plantilla (obligatorio cuando type=template)
          allOf:
            - $ref: '#/components/schemas/TemplatePayloadDto'
        mediaUrl:
          type: string
          description: URL del media (type=image|document)
          example: https://cdn.sofiachat.com/media/promo-agosto.jpg
        assignToHuman:
          type: boolean
          description: Si true, la conversación pasa a intervención humana (HITL)
          example: false
        metadata:
          type: object
          additionalProperties: true
          description: Metadatos libres que se guardan junto al mensaje
          example:
            source: crm
            ticketId: A-1001
      required:
        - channelId
        - type
    TemplatePayloadDto:
      type: object
      properties:
        name:
          type: string
          description: Nombre de la plantilla aprobada en Meta
          example: recordatorio_cita
        language:
          type: string
          description: Código de idioma de la plantilla, p.ej. es o en_US
          example: es_MX
        parameters:
          type: object
          additionalProperties:
            type: string
          description: >-
            Parámetros del body. NAMED: { nombre: valor }. POSITIONAL: { '1':
            valor, '2': valor }.
          example:
            nombre: Juan
            fecha: 3 de agosto
      required:
        - name
        - language
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-API-Key

````