openapi: 3.2.0
info:
  title: Messagebird Messages API
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
  description: 'Operations tagged Messages across 2 of this provider''s published API definitions: messagebird-conversations-openapi.yml, messagebird-sms-messaging-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://conversations.messagebird.com/v1
  description: Production Server
- url: https://rest.messagebird.com
  description: Production Server
security:
- accessKey: []
tags:
- name: Messages
  description: Operations for sending and retrieving messages within conversations.
paths:
  /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
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
  /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
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
  /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
    servers:
    - url: https://conversations.messagebird.com/v1
      description: Production Server
  /messages:
    get:
      operationId: listMessages
      summary: List messages
      description: Retrieves a list of SMS messages that have been sent or received. Messages are returned in reverse chronological order.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/offsetParam_2'
      - $ref: '#/components/parameters/limitParam_2'
      responses:
        '200':
          description: A list of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          description: Unauthorized
    post:
      operationId: createMessage
      summary: Send a new message
      description: Creates a new SMS message and sends it to the specified recipients. A single message can be sent to up to 50 recipients at a time. Messages longer than 160 characters are automatically split into multiple parts.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '201':
          description: Message created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
    servers:
    - url: https://rest.messagebird.com
      description: Production Server
  /messages/{id}:
    get:
      operationId: viewMessage
      summary: View a message
      description: Retrieves the information of an existing inbound or outbound SMS message. You only need to supply the unique message ID that was returned upon creation or receiving.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageIdParam_2'
      responses:
        '200':
          description: Message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorized
        '404':
          description: Message not found
    delete:
      operationId: deleteMessage
      summary: Delete a message
      description: Deletes an existing message. You only need to supply the unique message ID that was returned upon creation.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageIdParam_2'
      responses:
        '204':
          description: Message deleted
        '401':
          description: Unauthorized
        '404':
          description: Message not found
    servers:
    - url: https://rest.messagebird.com
      description: Production Server
components:
  schemas:
    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.
    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.
    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.
    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.
    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'
    Recipient:
      type: object
      properties:
        recipient:
          type: integer
          format: int64
          description: The recipient phone number.
        status:
          type: string
          description: The delivery status of the message.
          enum:
          - scheduled
          - sent
          - buffered
          - delivered
          - expired
          - delivery_failed
        statusDatetime:
          type: string
          format: date-time
          description: The date and time when the status was last updated.
    MessageList:
      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 in the current result set.
        totalCount:
          type: integer
          description: The total number of items available.
        links:
          type: object
          properties:
            first:
              type: string
              format: uri
              description: Link to the first page of results.
            previous:
              type: string
              format: uri
              description: Link to the previous page of results.
            next:
              type: string
              format: uri
              description: Link to the next page of results.
            last:
              type: string
              format: uri
              description: Link to the last page of results.
        items:
          type: array
          description: The list of messages.
          items:
            $ref: '#/components/schemas/Message'
    MessageCreate:
      type: object
      required:
      - recipients
      - originator
      - body
      properties:
        recipients:
          type: array
          description: The phone numbers that will receive the message in international format. A maximum of 50 recipients can be specified per request.
          items:
            type: string
          minItems: 1
          maxItems: 50
        originator:
          type: string
          description: The sender of the message. Can be a telephone number including country code or an alphanumeric string with a maximum length of 11 characters.
          maxLength: 17
        body:
          type: string
          description: The body of the SMS message. Messages longer than 160 characters will be split into multiple parts.
          maxLength: 1377
        type:
          type: string
          description: The type of message. Can be sms, binary, or flash.
          enum:
          - sms
          - binary
          - flash
          default: sms
        reference:
          type: string
          description: A client reference for tracking purposes.
        reportUrl:
          type: string
          format: uri
          description: The URL for delivery report callbacks for this message.
        validity:
          type: integer
          description: The validity period of the message in seconds.
        gateway:
          type: integer
          description: The SMS route used to send the message.
        typeDetails:
          type: object
          description: Additional type-specific details for the message.
        datacoding:
          type: string
          description: The encoding used for the message body. Use auto for automatic detection, unicode for Unicode, or plain for GSM encoding.
          enum:
          - plain
          - unicode
          - auto
          default: plain
        mclass:
          type: integer
          description: The message class. Set to 1 for flash messages.
          enum:
          - 0
          - 1
        scheduledDatetime:
          type: string
          format: date-time
          description: The scheduled date and time of the message in RFC 3339 format.
    Message:
      type: object
      properties:
        id:
          type: string
          description: A unique random ID for the message, generated by the MessageBird platform.
        href:
          type: string
          format: uri
          description: The URL of the message resource.
        direction:
          type: string
          description: The direction of the message. Can be mt (mobile terminated) for outbound or mo (mobile originated) for inbound.
          enum:
          - mt
          - mo
        type:
          type: string
          description: The type of message.
          enum:
          - sms
          - binary
          - flash
        originator:
          type: string
          description: The sender of the message.
        body:
          type: string
          description: The body of the SMS message.
        reference:
          type: string
          description: The client reference for the message.
        validity:
          type: integer
          description: The validity period of the message in seconds.
        gateway:
          type: integer
          description: The SMS route used to send the message.
        typeDetails:
          type: object
          description: Additional type-specific details.
        datacoding:
          type: string
          description: The encoding used for the message body.
        mclass:
          type: integer
          description: The message class.
        scheduledDatetime:
          type: string
          format: date-time
          description: The scheduled date and time of the message.
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the message was created.
        recipients:
          $ref: '#/components/schemas/Recipients'
    Recipients:
      type: object
      properties:
        totalCount:
          type: integer
          description: The total number of recipients.
        totalSentCount:
          type: integer
          description: The number of messages sent.
        totalDeliveredCount:
          type: integer
          description: The number of messages delivered.
        totalDeliveryFailedCount:
          type: integer
          description: The number of messages that failed to deliver.
        items:
          type: array
          description: The list of recipient details.
          items:
            $ref: '#/components/schemas/Recipient'
  parameters:
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
    messageIdParam:
      name: messageId
      in: path
      required: true
      description: The unique identifier of the message.
      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_2:
      name: offset
      in: query
      required: false
      description: The number of items to skip before starting to collect the result set.
      schema:
        type: integer
        default: 0
    messageIdParam_2:
      name: id
      in: path
      required: true
      description: The unique identifier of the message.
      schema:
        type: string
    limitParam_2:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
        maximum: 250
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
x-refined-from:
- messagebird-conversations-openapi.yml
- messagebird-sms-messaging-openapi.yml