openapi: 3.1.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
externalDocs:
  description: Conversations API Documentation
  url: https://developers.messagebird.com/api/conversations/
servers:
  - url: https://conversations.messagebird.com/v1
    description: Production Server
tags:
  - name: Conversations
    description: >-
      Operations for listing and managing conversations across channels.
  - name: Messages
    description: >-
      Operations for sending and retrieving messages within conversations.
  - name: Webhooks
    description: >-
      Operations for managing conversation webhooks that receive real-time
      event notifications.
security:
  - accessKey: []
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
  /conversations/{conversationId}/messages:
    get:
      operationId: listConversationMessages
      summary: List messages in a conversation
      description: >-
        Retrieves a paginated list of all messages within a specific
        conversation. Messages are returned with the newest first.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/conversationIdParam'
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessageList'
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
    post:
      operationId: sendConversationMessage
      summary: Send a message in a conversation
      description: >-
        Sends a new message within an existing conversation. The message
        will be delivered through the channel associated with the
        conversation.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/conversationIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationMessageSend'
      responses:
        '200':
          description: Message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessage'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
  /send:
    post:
      operationId: sendMessage
      summary: Send a message
      description: >-
        Sends a message to a recipient without requiring an existing
        conversation. MessageBird will automatically match or create a
        conversation for the recipient.
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageSend'
      responses:
        '200':
          description: Message accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessage'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /messages/{messageId}:
    get:
      operationId: viewMessage
      summary: View a message
      description: >-
        Retrieves the details of a specific message by its unique
        identifier.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/messageIdParam'
      responses:
        '200':
          description: Message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessage'
        '401':
          description: Unauthorized
        '404':
          description: Message not found
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      description: >-
        Retrieves a list of all configured conversation webhooks. The
        platform supports up to 10 channel-specific webhooks and 5
        generic webhooks.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          description: Unauthorized
    post:
      operationId: createWebhook
      summary: Create a webhook
      description: >-
        Creates a new webhook to receive real-time notifications for
        conversation events. Webhooks can be channel-specific or generic.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /webhooks/{webhookId}:
    get:
      operationId: viewWebhook
      summary: View a webhook
      description: >-
        Retrieves the details of a specific webhook by its unique
        identifier.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    patch:
      operationId: updateWebhook
      summary: Update a webhook
      description: >-
        Updates the configuration of an existing webhook.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: >-
        Deletes an existing webhook by its unique identifier.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '204':
          description: Webhook deleted
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
components:
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Access key authentication in the form of 'AccessKey {accessKey}'.
  parameters:
    conversationIdParam:
      name: conversationId
      in: path
      required: true
      description: >-
        The unique identifier of the conversation.
      schema:
        type: string
    messageIdParam:
      name: messageId
      in: path
      required: true
      description: >-
        The unique identifier of the message.
      schema:
        type: string
    webhookIdParam:
      name: webhookId
      in: path
      required: true
      description: >-
        The unique identifier of the webhook.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: >-
        The number of items to skip.
      schema:
        type: integer
        default: 0
    limitParam:
      name: limit
      in: query
      required: false
      description: >-
        The maximum number of items to return.
      schema:
        type: integer
        default: 20
  schemas:
    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.
    ConversationUpdate:
      type: object
      properties:
        status:
          type: string
          description: >-
            The new status for the conversation.
          enum:
            - active
            - archived
    ConversationMessageSend:
      type: object
      required:
        - type
        - content
      properties:
        type:
          type: string
          description: >-
            The type of message content.
          enum:
            - text
            - image
            - video
            - audio
            - file
            - location
            - hsm
        content:
          $ref: '#/components/schemas/MessageContent'
        channelId:
          type: string
          description: >-
            The channel to use for sending. If omitted, the last used
            channel in the conversation is used.
        reportUrl:
          type: string
          format: uri
          description: >-
            The URL for delivery status callbacks.
    MessageSend:
      type: object
      required:
        - to
        - from
        - type
        - content
      properties:
        to:
          type: string
          description: >-
            The recipient identifier.
        from:
          type: string
          description: >-
            The channel identifier to send from.
        type:
          type: string
          description: >-
            The type of message content.
          enum:
            - text
            - image
            - video
            - audio
            - file
            - location
            - hsm
        content:
          $ref: '#/components/schemas/MessageContent'
        reportUrl:
          type: string
          format: uri
          description: >-
            The URL for delivery status callbacks.
    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.
    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'
    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.
    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'
    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.
    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.
    WebhookCreate:
      type: object
      required:
        - channelId
        - url
        - events
      properties:
        channelId:
          type: string
          description: >-
            The channel to subscribe to. Omit for a generic webhook that
            receives events from all channels.
        url:
          type: string
          format: uri
          description: >-
            The URL to receive webhook payloads.
        events:
          type: array
          description: >-
            The list of events to subscribe to.
          items:
            type: string
            enum:
              - message.created
              - message.updated
              - conversation.created
              - conversation.updated
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the webhook.
        channelId:
          type: string
          description: >-
            The channel the webhook is subscribed to.
        url:
          type: string
          format: uri
          description: >-
            The URL that receives webhook payloads.
        events:
          type: array
          description: >-
            The events the webhook is subscribed to.
          items:
            type: string
        status:
          type: string
          description: >-
            The status of the webhook.
          enum:
            - enabled
            - disabled
        createdDatetime:
          type: string
          format: date-time
          description: >-
            The date and time when the webhook was created.
        updatedDatetime:
          type: string
          format: date-time
          description: >-
            The date and time when the webhook was last updated.
    WebhookList:
      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 webhooks.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'