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

# Envío de mensajes

> Envía mensajes desde tu canal a un usuario especificando el tipo de contenido. Soporta identificación por número de teléfono o BSUID.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
    --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
    --header 'Content-Type: application/json' \
    --data '{
      "type": "text",
      "text": "Hola, este es un mensaje de texto",
      "userId": "PHONE_NUMBER_OR_BSUID"
    }'
  ```
</RequestExample>

## Identificación del destinatario

El campo `userId` acepta dos formatos:

* **Número de teléfono**: formato E.164 sin el signo `+` (ej: `593999999999`).
* **BSUID (Business-Scoped User ID)**: un identificador con formato `CC.alfanumérico` (ej: `US.13491208655302741918`).

<Note>
  **¿Qué es un BSUID?** Cuando un usuario activa la protección de número en WhatsApp, Meta deja de exponer su número de teléfono real y en su lugar identifica al usuario mediante un BSUID único por negocio. Si tu integración ya conoce el BSUID de un usuario —por ejemplo, porque lo recibiste en un webhook entrante—, puedes usarlo directamente en `userId` para enviarle un mensaje sin necesitar su número de teléfono.
</Note>

<Tabs>
  <Tab title="Con número de teléfono">
    ```bash cURL theme={null}
    curl --request POST \
      --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
      --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
      --header 'Content-Type: application/json' \
      --data '{
        "type": "text",
        "text": "Hola, este es un mensaje de texto",
        "userId": "593999999999"
      }'
    ```
  </Tab>

  <Tab title="Con BSUID">
    ```bash cURL theme={null}
    curl --request POST \
      --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
      --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
      --header 'Content-Type: application/json' \
      --data '{
        "type": "text",
        "text": "Hola, este es un mensaje de texto",
        "userId": "US.13491208655302741918"
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  **Formato inválido:** si `userId` no corresponde a un número de teléfono ni a un BSUID con formato válido, la API responde con un error `400` (`INVALID_USER_ID`).
</Warning>

## Casos de Uso

* Notificaciones simples
* Confirmaciones
* Mensajes informativos
* Respuestas automáticas básicas
* Responder a un usuario que activó la privacidad de número en WhatsApp, usando el BSUID recibido en un webhook entrante
* Enviar mensajes proactivos a usuarios identificados exclusivamente por BSUID, sin necesidad de almacenar ni conocer su número de teléfono real

## Ejemplos

### Responder a un mensaje entrante identificado por BSUID

Cuando un usuario con privacidad de número activada te escribe, el webhook entrante trae su BSUID en vez de un teléfono. Usa ese mismo valor para responderle:

```bash cURL theme={null}
curl --request POST \
  --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
  --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "text",
    "text": "¡Gracias por escribirnos! En breve un agente te atenderá.",
    "userId": "US.13491208655302741918"
  }'
```

### Enviar una imagen a un destinatario identificado por BSUID

El resto de tipos de mensaje (imagen, documento, ubicación, etc.) funcionan igual: solo cambia el valor de `userId` por el BSUID del destinatario.

```bash cURL theme={null}
curl --request POST \
  --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
  --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "image",
    "mediaUrl": "https://example.com/catalogo.jpg",
    "userId": "US.13491208655302741918"
  }'
```


## OpenAPI

````yaml POST /v1/bots/{botId}/messages
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
  - name: Memory
    description: Per-user session memory management (Memory API v2)
paths:
  /v1/bots/{botId}/messages:
    post:
      tags:
        - Messages
      summary: Send Message
      description: >-
        Send a message to a user. Supports multiple message types including
        text, images, audio, video, files, stickers, location, contacts, and
        interactive elements.
      operationId: sendMessage
      parameters:
        - name: botId
          in: path
          required: true
          description: The unique identifier of the bot
          schema:
            type: string
          example: BOT_ID
      requestBody:
        required: true
        description: Message payload. The structure varies based on the message type.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/TextMessage'
                - $ref: '#/components/schemas/TextWithOptionsMessage'
                - $ref: '#/components/schemas/QuickReplyMessage'
                - $ref: '#/components/schemas/ImageMessage'
                - $ref: '#/components/schemas/AudioMessage'
                - $ref: '#/components/schemas/VideoMessage'
                - $ref: '#/components/schemas/FileMessage'
                - $ref: '#/components/schemas/StickerMessage'
                - $ref: '#/components/schemas/LocationMessage'
                - $ref: '#/components/schemas/ContactsMessage'
                - $ref: '#/components/schemas/LocationRequestMessage'
                - $ref: '#/components/schemas/CTAUrlMessage'
                - $ref: '#/components/schemas/VoiceCallMessage'
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    TextMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - text
            - userId
          properties:
            type:
              type: string
              enum:
                - text
              example: text
            text:
              type: string
              description: Text content of the message
              example: Hello, this is a text message
    TextWithOptionsMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - text
            - userId
            - buttons
          properties:
            type:
              type: string
              enum:
                - text
              example: text
            text:
              type: string
              description: Content of the message
              example: Please select an option
            buttons:
              $ref: '#/components/schemas/Buttons'
    QuickReplyMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - text
            - userId
            - quick_replies
          properties:
            type:
              type: string
              enum:
                - quick_reply
              example: quick_reply
            text:
              type: string
              example: Choose a quick reply
            title:
              type: string
              maxLength: 20
            quick_replies:
              type: array
              minItems: 1
              maxItems: 3
              items:
                $ref: '#/components/schemas/QuickReply'
    ImageMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - mediaUrl
            - userId
          properties:
            type:
              type: string
              enum:
                - image
              example: image
            mediaUrl:
              type: string
              format: uri
              example: https://example.com/image.jpg
            text:
              type: string
              example: Check out this image
    AudioMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - mediaUrl
            - userId
          properties:
            type:
              type: string
              enum:
                - audio
              example: audio
            mediaUrl:
              type: string
              format: uri
              example: https://example.com/audio.mp3
    VideoMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - mediaUrl
            - userId
          properties:
            type:
              type: string
              enum:
                - video
              example: video
            mediaUrl:
              type: string
              format: uri
              example: https://example.com/video.mp4
            text:
              type: string
    FileMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - mediaUrl
            - userId
          properties:
            type:
              type: string
              enum:
                - file
              example: file
            mediaUrl:
              type: string
              format: uri
              example: https://example.com/document.pdf
            text:
              type: string
            filename:
              type: string
              example: document.pdf
    StickerMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - mediaUrl
            - userId
          properties:
            type:
              type: string
              enum:
                - sticker
              example: sticker
            mediaUrl:
              type: string
              format: uri
              example: https://example.com/sticker.webp
    LocationMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - coordinates
            - userId
          properties:
            type:
              type: string
              enum:
                - location
              example: location
            coordinates:
              $ref: '#/components/schemas/Coordinates'
    ContactsMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - contacts
            - userId
          properties:
            type:
              type: string
              enum:
                - contacts
              example: contacts
            contacts:
              type: array
              items:
                $ref: '#/components/schemas/Contact'
    LocationRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - text
            - userId
          properties:
            type:
              type: string
              enum:
                - location_request
              example: location_request
            text:
              type: string
              example: Please share your location
    CTAUrlMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - title
            - text
            - caption
            - userId
            - parameters
          properties:
            type:
              type: string
              enum:
                - cta_url
              example: cta_url
            title:
              type: string
              example: Welcome
            text:
              type: string
              example: Visit our website
            caption:
              type: string
              example: Jelou
            parameters:
              $ref: '#/components/schemas/CTAUrlParameters'
    VoiceCallMessage:
      allOf:
        - $ref: '#/components/schemas/BaseMessage'
        - type: object
          required:
            - type
            - text
            - userId
            - parameters
          properties:
            type:
              type: string
              enum:
                - voice_call
              example: voice_call
            header:
              type: string
            text:
              type: string
            parameters:
              $ref: '#/components/schemas/VoiceCallParameters'
    MessageResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        messageId:
          type: string
          example: msg_123456789
    BaseMessage:
      type: object
      required:
        - type
        - userId
      properties:
        type:
          type: string
          description: Type of message to send
        userId:
          type: string
          description: >-
            Unique identifier of the user receiving the message. Accepts either
            a phone number in E.164 format without the leading '+' (e.g.
            '593999999999') or a BSUID (Business-Scoped User ID, e.g.
            'US.13491208655302741918') for users who have enabled phone number
            privacy in WhatsApp.
          example: '593999999999'
        botId:
          type: string
          description: Unique identifier of the bot sending the message
          example: BOT_ID
    Buttons:
      type: object
      required:
        - options
      properties:
        title:
          type: string
          description: Title displayed above the message
        buttonText:
          $ref: '#/components/schemas/ButtonText'
        options:
          type: array
          description: List of options (min 1, max 10)
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/ButtonOption'
    QuickReply:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          maxLength: 20
          example: 'Yes'
    Coordinates:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
          format: double
          example: 40.7128
        long:
          type: number
          format: double
          example: -74.006
    Contact:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ContactName'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/ContactPhone'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/ContactEmail'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/ContactAddress'
    CTAUrlParameters:
      type: object
      required:
        - url
        - display_text
      properties:
        url:
          type: string
          format: uri
          example: https://apps.jelou.ai
        display_text:
          type: string
          example: Visit Website
    VoiceCallParameters:
      type: object
      required:
        - display_text
      properties:
        display_text:
          type: string
          example: Talk to an advisor
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
    ButtonText:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
          default: Opciones
    ButtonOption:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          maxLength: 24
          example: Option 1
        description:
          type: string
          maxLength: 72
          example: This is option 1
        payload:
          type: string
          example: OPTION_1_PAYLOAD
    ContactName:
      type: object
      properties:
        formatted_name:
          type: string
          example: John Doe
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        middle_name:
          type: string
    ContactPhone:
      type: object
      properties:
        phone:
          type: string
          example: '+1234567890'
        type:
          type: string
          example: Mobile
        wa_id:
          type: string
    ContactEmail:
      type: object
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        type:
          type: string
          example: Work
    ContactAddress:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        country_code:
          type: string
        type:
          type: string
  responses:
    BadRequest:
      description: Bad request - Invalid format or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret

````