Bird Conversations API

openapi: 3.2.0
info:
  title: Bird Conversations API
  version: '1.0'
  description: 'Operations tagged Conversations across 2 of this provider''s published API definitions: bird-openapi.yml, messagebird-conversations-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bird.com
  description: Bird platform API
- url: https://rest.messagebird.com
  description: Legacy MessageBird REST API
- url: https://conversations.messagebird.com/v1
  description: Production Server
tags:
- name: Conversations
  description: Manage threaded omnichannel conversations.
paths:
  /workspaces/{workspaceId}/conversations:
    post:
      operationId: createConversation
      tags:
      - Conversations
      summary: Create a conversation
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
      security:
      - AccessKey: []
    servers:
    - url: https://api.bird.com
      description: Bird platform API
    - url: https://rest.messagebird.com
      description: Legacy MessageBird REST API
  /workspaces/{workspaceId}/conversations/{conversationId}/messages:
    post:
      operationId: createConversationMessage
      tags:
      - Conversations
      summary: Send a conversation message
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessage'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      security:
      - AccessKey: []
    servers:
    - url: https://api.bird.com
      description: Bird platform API
    - url: https://rest.messagebird.com
      description: Legacy MessageBird REST API
  /workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}:
    get:
      operationId: getConversationMessage
      tags:
      - Conversations
      summary: Get a conversation message
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/ConversationId'
      - name: messageId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      security:
      - AccessKey: []
    servers:
    - url: https://api.bird.com
      description: Bird platform API
    - url: https://rest.messagebird.com
      description: Legacy MessageBird REST API
  /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
      security:
      - accessKey: []
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
  /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_2'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - accessKey: []
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
  /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_2'
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
      security:
      - accessKey: []
    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_2'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
      security:
      - accessKey: []
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
components:
  schemas:
    CreateMessage:
      type: object
      required:
      - receiver
      properties:
        receiver:
          $ref: '#/components/schemas/Receiver'
        body:
          $ref: '#/components/schemas/MessageBody'
        template:
          type: object
          description: Template reference and variables (required when body is absent).
        tags:
          type: array
          items:
            type: string
    Receiver:
      type: object
      properties:
        contacts:
          type: array
          items:
            type: object
            properties:
              identifierValue:
                type: string
              identifierKey:
                type: string
    Conversation:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        channelId:
          type: string
        createdAt:
          type: string
          format: date-time
    Message:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        direction:
          type: string
          enum:
          - incoming
          - outgoing
        sender:
          type: object
        receiver:
          $ref: '#/components/schemas/Receiver'
        body:
          $ref: '#/components/schemas/MessageBody'
        createdAt:
          type: string
          format: date-time
    MessageBody:
      type: object
      properties:
        type:
          type: string
          enum:
          - text
          - image
          - file
          - html
        text:
          type: object
          properties:
            text:
              type: string
    CreateConversation:
      type: object
      properties:
        channelId:
          type: string
        participants:
          type: array
          items:
            type: object
    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.
    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_2'
    Conversation_2:
      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'
    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.
    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'
    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
    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.
  parameters:
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      description: Bird workspace identifier.
      schema:
        type: string
    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
    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: AccessKey token. Send as the Authorization header value "AccessKey {your-access-key}".
    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/
x-refined-from:
- bird-openapi.yml
- messagebird-conversations-api-openapi.yml