Dotdigital CPaaS API

openapi: 3.0.1
info:
  title: Omnichannel API
  description: 'Provides methods for sending single and batched outbound messages to any

    configured channel, as well as posting inbound messages and message or

    inbound status updates. Also supports retrieval, patching, and deletion of

    individual messages, enabling full lifecycle management of omnichannel

    communications.'
  version: 1.3.1
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      description: The Dotdigital region id your account belongs to
      enum:
      - r1
      - r2
      - r3
      default: r1
security:
- basicAuth: []
paths:
  /cpaas/messages/{messageId}/statuses/{status}:
    post:
      tags:
      - Omnichannel API
      summary: Posts a status for a message
      parameters:
      - name: messageId
        in: path
        description: The id of the message
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: status
        in: path
        description: The status of the message
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - failed
          - delivered
          - read
          - expired
          - sent
          - filtered
      requestBody:
        description: The status details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageStatus'
        required: true
      responses:
        '200':
          description: The status was received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageStatus'
        '400':
          description: Validation issues were found
          content: {}
        '404':
          description: The message was not found
          content: {}
      x-codegen-request-body-name: details
  /cpaas/messages/{messageId}:
    get:
      tags:
      - Omnichannel API
      summary: Retrieves the current state of a specific message.
      parameters:
      - name: messageId
        in: path
        description: The id of the message
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: The message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: The message was not found
          content: {}
    delete:
      tags:
      - Omnichannel API
      summary: Deletes a Message
      parameters:
      - name: messageId
        in: path
        description: The id of the message
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Indicates successful deletetion of a Message
          content: {}
        '404':
          description: The Message was not found
          content: {}
        '409':
          description: A concurrency issue occured deleting the Message
          content: {}
    patch:
      tags:
      - Omnichannel API
      summary: Patches a Message
      parameters:
      - name: messageId
        in: path
        description: The id of the message
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: Patch options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessagePatchBase'
        required: true
      responses:
        '202':
          description: Indicates successful patch of a Message
          content: {}
        '400':
          description: Validation issues were found
          content: {}
        '404':
          description: The Message was not found
          content: {}
        '409':
          description: A concurrency issue occured
          content: {}
      x-codegen-request-body-name: message
  /cpaas/messages:
    post:
      tags:
      - Omnichannel API
      summary: Send a new message
      requestBody:
        description: The message details and options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageBase'
        required: true
      responses:
        '201':
          description: The message was accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Validation issues were found
          content: {}
      x-codegen-request-body-name: message
  /cpaas/messages/batch:
    post:
      tags:
      - Omnichannel API
      summary: Send a batch of new messages
      requestBody:
        description: The message details and options
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MessageBase'
        required: true
      responses:
        '202':
          description: The batch was accepted
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/inline_response_202'
        '400':
          description: Validation issues were found
          content: {}
      x-codegen-request-body-name: message
  /cpaas/messages/inbounds:
    post:
      tags:
      - Omnichannel API
      summary: Posts an inbound message
      requestBody:
        description: The inbound message details and options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundMessage'
        required: true
      responses:
        '201':
          description: The message was accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessage'
        '400':
          description: Validation issues were found
          content: {}
      x-codegen-request-body-name: inbound
  /cpaas/messages/inbounds/{inboundMessageId}/statuses/{status}:
    post:
      tags:
      - Omnichannel API
      summary: Posts a status for an inbound
      parameters:
      - name: inboundMessageId
        in: path
        description: The id of the inbound message
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: status
        in: path
        description: The status of the inbound message
        required: true
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - delivered
          - read
      requestBody:
        description: The inbound message status detail
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundMessageStatus'
        required: true
      responses:
        '200':
          description: The inbound message status was received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessage'
        '400':
          description: Validation issues were found
          content: {}
        '404':
          description: The inbound message was not found
          content: {}
      x-codegen-request-body-name: details
components:
  schemas:
    Message:
      type: object
      properties:
        messageId:
          type: string
          description: Unique id for this message
          readOnly: true
        sentOn:
          type: string
          description: Date/Time (in UTC, ISO 8601 format) that the message sent was accepted
          format: date-time
          readOnly: true
        status:
          type: string
          description: Current status of the message
          readOnly: true
          enum:
          - processing
          - retrying
          - sent
          - delivered
          - read
          - expired
          - failed
          - filtered
        statusDetails:
          type: object
          properties: {}
          description: Specific details related to the current status
        _createdOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the message was created
          format: date-time
          readOnly: true
        _createdBy:
          type: string
          description: The identity that created the message
        _updatedOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the message was last updated
          format: date-time
          readOnly: true
        _updatedBy:
          type: string
          description: The identity that created the message
          readOnly: true
        metadata:
          type: object
          additionalProperties: true
          description: 'Custom metadata relating to the message. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: {{profile.forename}}'
        to:
          $ref: '#/components/schemas/to'
        title:
          type: string
          description: 'The title to use to describe the message (if supported by the channel). Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: Hello {{profile.forename}}'
        body:
          type: string
          description: 'This is the default text based body to be used, if no body override is declared for a channel. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: Hello {{profile.forename}}'
        customBody:
          $ref: '#/components/schemas/customBody'
        overrides:
          $ref: '#/components/schemas/Message_overrides'
        channelOptions:
          $ref: '#/components/schemas/channelOptions'
        conversationId:
          type: string
          description: Optional conversationId, used to correlate messages within the platform and on any external channels, if supported.
        expiresOn:
          type: string
          description: Date/Time (in UTC, ISO 8601 format) that the should expire (if supported by the selected channel).
          format: date-time
        rules:
          type: array
          description: The channels to attempt for this message, in order of priority
          items:
            type: string
            example: sms
        messageParts:
          type: array
          description: (Additional) parts to be sent with the message, as native components where supported, or attachments / links.
          items:
            $ref: '#/components/schemas/MessagePart'
    MessagePart:
      required:
      - type
      type: object
      properties:
        channels:
          type: array
          description: A list of channels to which this message part applies
          items:
            type: string
        name:
          type: string
          description: A name for the part
        type:
          type: string
          description: The mime type (if applicable) sof the part
        url:
          type: string
          description: A url associated with the message part
        data:
          oneOf:
          - title: Text based content
            type: string
          - title: Binary data in Base64
            type: string
            format: binary
          - title: Object representing the content
            type: object
        size:
          type: integer
          description: Size of the message part in bytes
      description: Details of a single part that makes up a message
    MessageStatus:
      required:
      - channel
      type: object
      properties:
        channel:
          type: string
          description: The id of the channel the status is for.
        channelStatus:
          type: object
          additionalProperties: true
          description: Status data from the channel.
        timestamp:
          type: string
          description: The date (in UTC, ISO 8601 format) of the message status
          format: date-time
        failureReason:
          type: string
          description: A plain-english description of the reason for failure
    InboundMessage:
      required:
      - channel
      - from
      type: object
      properties:
        messageId:
          type: string
          description: Unique id for this inbound message
          readOnly: true
        receivedOn:
          type: string
          description: Date/Time (in UTC, ISO 8601 format) that the message sent was received
          format: date-time
          readOnly: true
        status:
          type: string
          description: Current status of the inbound message
          readOnly: true
          enum:
          - received
          - delivered
          - read
        from:
          type: object
          additionalProperties: true
          description: Any id fields to help identify the sender (fbmessengerId, phoneNumber)
        channel:
          type: string
          description: The id of the channel the inbound is being sent to.
        to:
          type: object
          additionalProperties: true
          description: Any id fields to help identify the recipient (pageId, phoneNumber)
        title:
          type: string
          description: Optional title field for the message.
        body:
          type: string
          description: A simple string representation of the message.
        conversationId:
          type: string
          description: Optional string containing a correlation id for the message.
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata relating to the message.
        channelData:
          $ref: '#/components/schemas/InboundMessage_channelData'
        messageParts:
          type: array
          description: Additional inbound message parts / attachments
          items:
            $ref: '#/components/schemas/MessagePart'
        correlation:
          $ref: '#/components/schemas/InboundMessage_correlation'
        _createdOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the inbound message was created
          format: date-time
          readOnly: true
        _createdBy:
          type: string
          description: The identity that created the inbound message
        _updatedOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the inbound message was last updated
          format: date-time
          readOnly: true
        _updatedBy:
          type: string
          description: The identity that created the inbound message
          readOnly: true
    InboundMessageStatus:
      required:
      - timestamp
      type: object
      properties:
        channelStatus:
          type: object
          additionalProperties: true
          description: Status data from the receiving channel.
        timestamp:
          type: string
          description: The date (in UTC, ISO 8601 format) of the inbound message status
          format: date-time
    to:
      type: object
      properties:
        phoneNumber:
          type: string
          description: Phone number, international format
        email:
          type: string
          description: Email address
        profileId:
          type: string
          description: Profile Id, used for App Messaging or to resolve other details from saved profiles.
        fbMessengerId:
          type: string
          description: Facebook Messenger Id
      additionalProperties:
        type: string
      description: Set of identifiers for the message recipient.
    customBody:
      type: object
      properties:
        appMessaging:
          type: object
          additionalProperties: true
          description: Configuration for the app messaging send.
        sms:
          type: object
          additionalProperties: true
          description: Specific details for the SMS channel
        mms:
          type: object
          additionalProperties: true
          description: Specific details for the MMS channel
        fbMessenger:
          type: object
          additionalProperties: true
          description: Specific details for the Facebook Messenger channel
        nativePush:
          type: object
          additionalProperties: true
          description: Specific details for the Native Push channel
        whatsApp:
          type: object
          additionalProperties: true
          description: Specific details for the What's App channel
        rcs:
          type: object
          additionalProperties: true
          description: Specific details for the RCS channel
      additionalProperties: true
      description: 'Custom body for specific channels.  All values specified will be copied onto the payload at the point of sending. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: {{profile.forename}}'
    channelOptions:
      type: object
      properties:
        appMessaging:
          $ref: '#/components/schemas/channelOptions_appMessaging'
        sms:
          $ref: '#/components/schemas/channelOptions_sms'
        mms:
          $ref: '#/components/schemas/channelOptions_mms'
        fbMessenger:
          $ref: '#/components/schemas/channelOptions_fbMessenger'
        whatsApp:
          $ref: '#/components/schemas/channelOptions_whatsApp'
        rcs:
          $ref: '#/components/schemas/channelOptions_rcs'
        nativePush:
          $ref: '#/components/schemas/channelOptions_nativePush'
      additionalProperties:
        type: object
        properties: {}
        description: Configuration for other channels.
      description: 'Configuration switches for specific channels. If a channel has a customBody as well as values in here, it will return a validation failure. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: Hello {{profile.forename}}'
    MessageBase:
      required:
      - rules
      - to
      type: object
      properties:
        metadata:
          type: object
          additionalProperties: true
          description: 'Custom metadata relating to the message. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: {{profile.forename}}'
        to:
          $ref: '#/components/schemas/to'
        title:
          type: string
          description: 'The title to use to describe the message (if supported by the channel). Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: Hello {{profile.forename}}'
        body:
          type: string
          description: 'This is the default text based body to be used, if no body override is declared for a channel. Profile data can be substituted anywhere by using the syntax {{profile.fieldName}} - example: Hello {{profile.forename}}'
        templateId:
          type: string
          description: This is the template id to be used to generate messageParts for this message
        customBody:
          $ref: '#/components/schemas/customBody'
        overrides:
          $ref: '#/components/schemas/Message_overrides'
        channelOptions:
          $ref: '#/components/schemas/channelOptions'
        conversationId:
          type: string
          description: Optional conversationId, used to correlate messages within the platform and on any external channels, if supported.
        expiresOn:
          type: string
          description: Date/Time (in UTC, ISO 8601 format) that the should expire (if supported by the selected channel).
          format: date-time
        rules:
          type: array
          description: The channels to attempt for this message, in order of priority
          items:
            type: string
            example: sms
        messageParts:
          type: array
          description: (Additional) parts to be sent with the message, as native components where supported, or attachments / links.
          items:
            $ref: '#/components/schemas/MessagePart'
        requireOptIn:
          type: boolean
          description: If requireOptIn is set to true, the message will be rejected if the target profile has not opted-in to any of the specified channels
    MessagePatchBase:
      required:
      - redact
      type: object
      properties:
        redact:
          type: boolean
        redactSource:
          type: string
          description: The source of the message redacting
          enum:
          - message
          - chat
    inline_response_202:
      required:
      - index
      - messageId
      type: object
      properties:
        index:
          type: number
          description: The 0-based index of the message in the batch
        messageId:
          type: string
          description: The id of the message
    Message_overrides_appMessaging:
      type: object
      properties:
        conversation:
          type: object
          additionalProperties: true
          description: Overrides for any conversation created for the message send
      description: Overrides for the app messaging send.
    Message_overrides:
      type: object
      properties:
        appMessaging:
          $ref: '#/components/schemas/Message_overrides_appMessaging'
      description: Details of any overrides allowed for the message send on any of the channels
    InboundMessage_channelData:
      type: object
      properties:
        body:
          type: object
          additionalProperties: true
          description: Data relating to the inbound message.
    InboundMessage_correlation:
      required:
      - messageId
      type: object
      properties:
        messageId:
          type: string
          description: The outbound message id
        metadata:
          type: object
          additionalProperties: true
          description: The outbound metadata
          readOnly: true
      description: Data relating to the outbound this inbound is in reply to
    channelOptions_appMessaging_from:
      type: object
      properties:
        profileId:
          type: string
          description: The id of the profile to send from
        name:
          type: string
          description: Name to display
        avatarUrl:
          type: string
          description: URL for an avatar to display with this message
      description: Set of identifiers for the message sender.
    channelOptions_appMessaging:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/channelOptions_appMessaging_from'
      description: Options for the app messaging send.
    channelOptions_sms_unicodeConversion_customReplacements:
      type: object
      properties:
        from:
          type: string
          description: Character that should be replaced
        to:
          type: string
          description: Character that will be replaced
    channelOptions_sms_unicodeConversion:
      type: object
      properties:
        convertUnicodeToGsm:
          type: boolean
          description: Enables automatic conversion of some Unicode characters to their GSM equivalents
        customReplacements:
          type: array
          description: Describe custom unicode replacements for picked signs
          items:
            $ref: '#/components/schemas/channelOptions_sms_unicodeConversion_customReplacements'
      description: Unicode conversion settings
    channelOptions_sms:
      type: object
      properties:
        from:
          minLength: 3
          type: string
          description: An alpha or long number to send from
        allowUnicode:
          type: boolean
          description: Allows unicode characters to be sent over SMS
        unicodeConversion:
          $ref: '#/components/schemas/channelOptions_sms_unicodeConversion'
      description: Options for the SMS channel
    channelOptions_mms:
      type: object
      properties:
        from:
          minLength: 3
          type: string
          description: An alpha or long number to send from
        allowUnicode:
          type: boolean
          description: Allows unicode characters to be sent over MMS
        unicodeConversion:
          $ref: '#/components/schemas/channelOptions_sms_unicodeConversion'
      description: Options for the MMS channel
    channelOptions_fbMessenger:
      type: object
      properties:
        messageTag:
          type: string
          description: Send message with one of predefined tag specified by facebook
        messagingType:
          type: string
          description: The Facebook messaging_type value
      description: Options for the Facebook Messenger channel
    channelOptions_whatsApp:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phoneNumber to send the message from. Default from channel configuration will be used if not specified.
        enableUrlPreview:
          type: boolean
          description: If set for true and url provided in message body, WhatsApp will display url preview
      description: Options for the WhatsApp channel
    channelOptions_rcs:
      type: object
      properties:
        agentId:
          type: string
          description: The agentId for the RCS Channel.
      description: Options for the RCS channel
    channelOptions_nativePush_data:
      type: object
      properties:
        fcm:
          type: object
          properties: {}
          description: Json object that will be sent in the push message for the app to use
        apns:
          type: object
          properties: {}
          description: Json object that will be sent in the push message for the app to use
        isSilent:
          type: boolean
          description: Should the push message trigger UI notification on the device. The default is true.
      description: Additional data passed to push message
    channelOptions_nativePush_deepLink_fcm:
      required:
      - url
      type: object
      properties:
        url:
          type: string
          description: Deep link URL that should be opened when the push notification is clicked
      description: ''
    channelOptions_nativePush_deepLink:
      type: object
      properties:
        trackingLink:
          type: string
          description: URL to be called by the SDK to report push notification click.
        fcm:
          $ref: '#/components/schemas/channelOptions_nativePush_deepLink_fcm'
        apns:
          $ref: '#/components/schemas/channelOptions_nativePush_deepLink_fcm'
      description: Deep link details
    channelOptions_nativePush:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/channelOptions_nativePush_data'
        deepLink:
          $ref: '#/components/schemas/channelOptions_nativePush_deepLink'
      description: Options for the native push channel
  parameters:
    apiSpacePathParameter:
      name: apiSpaceId
      in: path
      description: The api space id
      required: true
      schema:
        pattern: ^([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})|[a-f0-9]{32}$
        type: string
    messageIdPathParameter:
      name: messageId
      in: path
      description: The id of the message
      required: true
      schema:
        type: string
    statusPathParameter:
      name: status
      in: path
      description: The status of the message
      required: true
      schema:
        type: string
        enum:
        - failed
        - delivered
        - read
        - expired
        - sent
        - filtered
    mirrorChannelPathParameter:
      name: channel
      in: path
      description: The channel being mirrored
      required: true
      schema:
        type: string
        enum:
        - sms
    inboundMessageIdPathParameter:
      name: inboundMessageId
      in: path
      description: The id of the inbound message
      required: true
      schema:
        type: string
    inboundStatusPathParameter:
      name: status
      in: path
      description: The status of the inbound message
      required: true
      schema:
        type: string
        enum:
        - delivered
        - read
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-readme.samples-languages:
- curl
- csharp
- java
- node
- php
- python
- ruby
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true