> ## 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.

# URL Externa

> Envie uma mensagem com um botão que abre uma URL

<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": "cta_url",
      "title": "Welcome",
      "text": "Visit our website to learn more",
      "caption": "Jelou",
      "userId": "USER_ID",
      "parameters": {
        "url": "https://apps.jelou.ai",
        "display_text": "Visit Website"
      }
    }'
  ```
</RequestExample>

## Boas Práticas

<Note>
  **URLs Seguras:** Certifique-se de que as URLs são HTTPS e forneça um texto de botão claro e orientado para a ação.
</Note>

## Casos de Uso

* Direcionar usuários para sites externos
* Vincular a aplicações web
* Compartilhar recursos online
* Redirecionar para formulários ou páginas de cadastro


## 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
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
          example: USER_ID
        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

````