openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Conversations API
  description: The MessageBird Balance API provides developers with access to their account balance information. It returns the current payment type, available amount, and currency for the account associated with the API key. This API is useful for monitoring credit usage, building billing dashboards, and setting up automated alerts when account balances fall below a threshold.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://rest.messagebird.com
  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:
    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'
    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'
    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.
    ConversationUpdate:
      type: object
      properties:
        status:
          type: string
          description: The new status for the conversation.
          enum:
          - active
          - archived
    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.
    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'
    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.
    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.
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
    conversationIdParam:
      name: conversationId
      in: path
      required: true
      description: The unique identifier of the conversation.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Balance API Documentation
  url: https://developers.messagebird.com/api/balance/