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

# Send Message to Phone

> Send a message to a WhatsApp phone number. Doesn't require a previous chat or contact with the recipient.



## OpenAPI

````yaml post /messages
openapi: 3.0.3
info:
  title: Timelines Public API
  description: >
    # Timelines Public API


    _Some API calls may utilize message sending quota or be subject to message
    sending rate limits as described below._


    ### Credit Utilization 
      - Sending a message via API consumes 1 credit from message sending quota.
      - Sending a message with non-empty text and attachment consumes 2 credits from message sending quota.
      - If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), message sending quota will be restored (usually within a couple of hours).
    ### Message sending rate
      - Messages will be sent with random delay of about 2 seconds between each two messages (to avoid WhatsApp spam detection mechanisms). Contact support@timelines.global if you want to modify delay for your workspace (available on Business plan only).
      - If you exceed message sending frequency, messages be queued and sent out with delay. Each queued message will consume a message sending credit, so the number of queued messages cannot exceed the available quota.
      
    ### Authorization:
      - Copy API token from [Public API page](https://app.timelines.global/integrations/api/) in your Timelines Global account.
      - Put the token in *Authorization* header of request as follows:
      ```
      Authorization: Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8
      ```
            
    ### Message formatting:
      - use "\n" for line breaks
  version: 1.3.0
servers:
  - url: https://app.timelines.global/integrations/api
    description: Production
  - url: https://staging.app.timelines.global/integrations/api
    description: Staging
security:
  - bearerAuth: []
paths:
  /messages:
    post:
      summary: Send message to phone number
      description: >-
        Send message to a WhatsApp phone number (doesn't require to have
        previous chat or contact with the recipient). Optionally specify
        WhatsApp Account to use for sending. If omitted, will use the most
        recently connected WhatsApp account in the workspace. A message may
        contain a plaintext body or an attachment or both.
      requestBody:
        description: A JSON describing recipient and message payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageToPhone'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSendResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    MessageToPhone:
      allOf:
        - type: object
          required:
            - phone
          properties:
            phone:
              type: string
              description: >-
                a phone number, formatted according to international phone
                number standard, i.e.: [+][country code][area code][local phone
                number]
              example: '+14840000000'
            whatsapp_account_phone:
              type: string
              description: >-
                the WhatsApp account (as a phone number, in international
                format) to which the chat specified by JID belongs to. If
                omitted, the most recently connected WhatsApp account in the
                workspace will be used.
              example: '+14841111111'
        - $ref: '#/components/schemas/Message'
    MessageSendResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          example: ok
          enum:
            - ok
            - error
        data:
          $ref: '#/components/schemas/MessageID'
    Message:
      type: object
      properties:
        text:
          type: string
          description: plain text message
          example: hello, world!
        file_uid:
          type: string
          description: attachment UID
          example: afa9d4dd-978d-4a14-aa1b-bd65c272e645
        label:
          type: string
          description: >-
            assign label to the chat, in which the message is sent (create new
            label, if not exists)
          example: customer
        chat_name:
          type: string
          description: an exact name of the chat (or group) as appears in Timelines Global)
          example: MyChat
        attachment_template_id:
          type: integer
          description: >-
            a template ID of the attachment to be sent. The template must be
            created in the workspace before sending a message with it.
          example: 123456
    MessageID:
      type: object
      required:
        - message_uid
      properties:
        message_uid:
          type: string
    ErrorResponse:
      required:
        - message
        - status
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          example: error
          enum:
            - ok
            - error
  responses:
    BadRequestError:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Access token is missing or invalid
    AccessDenied:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Specified entities not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````