openapi: 3.2.0
info:
  title: MessageBird Conversations API
  description: The MessageBird Conversations API provides a unified interface for managing omnichannel messaging across platforms such as SMS, WhatsApp, Facebook Messenger, Telegram, and more. It consolidates messages from multiple channels into a single conversation thread per contact, enabling consistent customer communication. The API supports sending and receiving messages, managing conversation state, and handling webhooks for real-time event processing.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://conversations.messagebird.com/v1
  description: Production Server
security:
- accessKey: []
tags:
- name: Conversations
  description: Operations for listing and managing conversations across channels.
paths:
  /conversations:
    get:
      operationId: listConversations
      summary: List conversations
      description: Retrieves a paginated list of all conversations. Conversations are returned in reverse chronological order based on the last received message.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - name: status
        in: query
        required: false
        description: Filter conversations by status.
        schema:
          type: string
          enum:
          - active
          - archived
      responses:
        '200':
          description: A list of conversations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '401':
          description: Unauthorized
  /conversations/start:
    post:
      operationId: startConversation
      summary: Start a conversation
      description: Starts a new conversation by sending a message to a contact. If a conversation already exists with the contact, the message is added to the existing conversation.
      tags:
      - Conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationStart'
      responses:
        '200':
          description: Conversation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /conversations/{conversationId}:
    get:
      operationId: viewConversation
      summary: View a conversation
      description: Retrieves the details of a specific conversation by its unique identifier.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/conversationIdParam'
      responses:
        '200':
          description: Conversation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
    patch:
      operationId: updateConversation
      summary: Update a conversation
      description: Updates the status of an existing conversation, such as archiving or reactivating it.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/conversationIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationUpdate'
      responses:
        '200':
          description: Conversation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
components:
  schemas:
    Channel:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the channel.
        name:
          type: string
          description: The name of the channel.
        platformId:
          type: string
          description: The platform identifier for the channel.
          enum:
          - sms
          - whatsapp
          - facebook
          - telegram
          - line
          - wechat
          - email
        status:
          type: string
          description: The status of the channel.
          enum:
          - active
          - inactive
          - pending
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the channel was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the channel was last updated.
    MessageContent:
      type: object
      description: The content of the message. The structure depends on the message type.
      properties:
        text:
          type: string
          description: The text content of the message, used when type is text.
        image:
          type: object
          description: The image content, used when type is image.
          properties:
            url:
              type: string
              format: uri
              description: The URL of the image.
            caption:
              type: string
              description: An optional caption for the image.
        video:
          type: object
          description: The video content, used when type is video.
          properties:
            url:
              type: string
              format: uri
              description: The URL of the video.
            caption:
              type: string
              description: An optional caption for the video.
        audio:
          type: object
          description: The audio content, used when type is audio.
          properties:
            url:
              type: string
              format: uri
              description: The URL of the audio file.
        file:
          type: object
          description: The file content, used when type is file.
          properties:
            url:
              type: string
              format: uri
              description: The URL of the file.
            caption:
              type: string
              description: An optional caption for the file.
        location:
          type: object
          description: The location content, used when type is location.
          properties:
            latitude:
              type: number
              format: double
              description: The latitude coordinate.
            longitude:
              type: number
              format: double
              description: The longitude coordinate.
        hsm:
          type: object
          description: The HSM (Highly Structured Message) template content, used for WhatsApp template messages.
          properties:
            namespace:
              type: string
              description: The namespace of the template.
            templateName:
              type: string
              description: The name of the template.
            language:
              type: object
              properties:
                policy:
                  type: string
                  description: The language policy.
                code:
                  type: string
                  description: The language code.
            params:
              type: array
              description: The template parameters.
              items:
                type: object
                properties:
                  default:
                    type: string
                    description: The default value for the parameter.
    ConversationList:
      type: object
      properties:
        offset:
          type: integer
          description: The offset of the result set.
        limit:
          type: integer
          description: The limit applied to the result set.
        count:
          type: integer
          description: The number of items returned.
        totalCount:
          type: integer
          description: The total number of conversations.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
    ConversationMessage:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the message.
        conversationId:
          type: string
          description: The conversation this message belongs to.
        channelId:
          type: string
          description: The channel through which the message was sent or received.
        platform:
          type: string
          description: The platform of the channel.
        to:
          type: string
          description: The recipient identifier.
        from:
          type: string
          description: The sender identifier.
        direction:
          type: string
          description: The direction of the message.
          enum:
          - sent
          - received
        status:
          type: string
          description: The delivery status of the message.
          enum:
          - accepted
          - pending
          - sent
          - delivered
          - read
          - failed
          - deleted
        type:
          type: string
          description: The type of message content.
        content:
          $ref: '#/components/schemas/MessageContent'
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the message was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the message was last updated.
    Contact:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the contact.
        href:
          type: string
          format: uri
          description: The URL of the contact resource.
        msisdn:
          type: string
          description: The phone number of the contact.
        displayName:
          type: string
          description: The display name of the contact.
        firstName:
          type: string
          description: The first name of the contact.
        lastName:
          type: string
          description: The last name of the contact.
        customDetails:
          type: object
          description: Custom details associated with the contact.
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the contact was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the contact was last updated.
    ConversationMessageList:
      type: object
      properties:
        offset:
          type: integer
          description: The offset of the result set.
        limit:
          type: integer
          description: The limit applied to the result set.
        count:
          type: integer
          description: The number of items returned.
        totalCount:
          type: integer
          description: The total number of messages.
        items:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
    ConversationUpdate:
      type: object
      properties:
        status:
          type: string
          description: The new status for the conversation.
          enum:
          - active
          - archived
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the conversation.
        contactId:
          type: string
          description: The unique identifier of the contact.
        contact:
          $ref: '#/components/schemas/Contact'
        channels:
          type: array
          description: The channels used in this conversation.
          items:
            $ref: '#/components/schemas/Channel'
        status:
          type: string
          description: The status of the conversation.
          enum:
          - active
          - archived
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the conversation was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the conversation was last updated.
        lastReceivedDatetime:
          type: string
          format: date-time
          description: The date and time of the last received message.
        lastUsedChannelId:
          type: string
          description: The identifier of the last channel used in the conversation.
        messages:
          $ref: '#/components/schemas/ConversationMessageList'
    ConversationStart:
      type: object
      required:
      - to
      - type
      - content
      - channelId
      properties:
        to:
          type: string
          description: The identifier of the recipient, such as a phone number or platform-specific ID.
        type:
          type: string
          description: The type of message content being sent.
          enum:
          - text
          - image
          - video
          - audio
          - file
          - location
          - hsm
        content:
          $ref: '#/components/schemas/MessageContent'
        channelId:
          type: string
          description: The unique identifier of the channel to use for sending.
        reportUrl:
          type: string
          format: uri
          description: The URL to receive delivery status callbacks.
  parameters:
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
    conversationIdParam:
      name: conversationId
      in: path
      required: true
      description: The unique identifier of the conversation.
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Conversations API Documentation
  url: https://developers.messagebird.com/api/conversations/