openapi: 3.0.1
info:
  title: Respond.io Developer Comments Messages API
  description: REST API for the respond.io omnichannel customer-conversation management platform. Manage contacts, send and read messages across connected channels, open and close conversations, assign users, post internal comments, manage tags and custom fields, and configure webhooks. Requests and responses are JSON. Contacts are addressed by an identifier of the form `id:{id}`, `email:{email}`, or `phone:{phone}`.
  termsOfService: https://respond.io/terms-and-conditions
  contact:
    name: Respond.io Support
    url: https://developers.respond.io/
  version: '2.0'
servers:
- url: https://api.respond.io/v2
security:
- bearerAuth: []
tags:
- name: Messages
  description: Send messages to contacts and read message history.
paths:
  /contact/{identifier}/message:
    post:
      operationId: sendMessage
      tags:
      - Messages
      summary: Send a message
      description: Sends a message to a contact through a specific channel. If channelId is omitted, the message is sent through the last interacted channel.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageSend'
      responses:
        '200':
          description: Message accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResult'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/{identifier}/message/{messageId}:
    get:
      operationId: getMessage
      tags:
      - Messages
      summary: Get a message
      description: Retrieves a single message from a contact's conversation by message id.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      - name: messageId
        in: path
        required: true
        description: The message identifier.
        schema:
          type: integer
      responses:
        '200':
          description: The message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    MessageResult:
      type: object
      properties:
        messageId:
          type: integer
        status:
          type: string
          example: queued
    MessageContent:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text
          - attachment
          - quick_reply
          - whatsapp_template
        text:
          type: string
          description: Body text for type text or quick_reply.
        attachment:
          type: object
          properties:
            type:
              type: string
              enum:
              - image
              - video
              - audio
              - file
            url:
              type: string
              format: uri
        quickReplies:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              payload:
                type: string
        template:
          type: object
          description: WhatsApp template payload (name, languageCode, components).
          additionalProperties: true
    MessageSend:
      type: object
      required:
      - message
      properties:
        channelId:
          type: integer
          description: Target channel id. Omit to use the last interacted channel.
        message:
          $ref: '#/components/schemas/MessageContent'
    Message:
      type: object
      properties:
        messageId:
          type: integer
        contactId:
          type: integer
        channelId:
          type: integer
        traffic:
          type: string
          enum:
          - incoming
          - outgoing
        message:
          $ref: '#/components/schemas/MessageContent'
        timestamp:
          type: integer
        status:
          type: string
          description: Delivery status (sent, delivered, read, failed).
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
  parameters:
    Identifier:
      name: identifier
      in: path
      required: true
      description: Contact identifier in the form id:{id}, email:{email}, or phone:{phone}.
      schema:
        type: string
      example: phone:+60123456789
  responses:
    RateLimited:
      description: Too many requests. Limited to 5 requests per second per method.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Access Token from Settings > Integrations > Developer API, sent in the Authorization header as `Bearer {token}`.