openapi: 3.2.0
info:
  title: Inbox 2.0 API Reference Proactive Messaging Rest API
  description: Inbox 2.0 API Reference
  version: v1
  x-logo:
    url: static/hootsuite-logo.png
  contact:
    email: dev.support@hootsuite.com
  license:
    name: Hootsuite Developer Terms and API License Agreement
    url: https://hootsuite.com/legal/dev-api-terms
servers:
- url: https://platform.hootsuite.com
  description: Inbox 2.0 production server
security:
- bearer-token: []
tags:
- name: proactive_messaging_rest_api
  x-displayName: REST API
  description: "When calling the Proactive Messaging API, the client needs to be authenticated.  \n\nThe [REST API authentication](#tag/rest-api-authentication) section contains more details on how to authenticate your client.\n\n### Examples\n\n1. Send a proactive text message\n\nThe following example shows a proactive outbound message that can be sent as a text message. Inbox 2.0 supports text messaging on WhatsApp\nEnterprises are responsible for ensuring that the customers have opted-in for proactive communications.\n\nRequest\n\n```shell\ncurl -X POST https://platform.hootsuite.com/inbox/v1/proactive-messaging/ \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{ \"medium\": \"WHATSAPP\", \"channel\": \"myChannel\", \"contact\": \"+32495123456\", \"text\": \"Hello world!\" }'\n```\n\nResponse `200`\n\n```json\n{\n  \"correlationId\": \"3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66\"\n}\n```\n\n2. Send a proactive message template (WhatsApp)\n\nWhatsApp allows for proactive outbound communication when these are sent as message templates that have been authorized by WhatsApp. These templates have a name, corresponding text, and substitution parameters within the text to make them personalized.\nInbox 2.0 has simplified how enterprises can send out these message templates through the use of shorthand codes for inline syntax:\n\n```text\n&((namespace=[[NAMESPACE]] template=[[TEMPLATE NAME]] fallback=[[FALLBACK TEXT]] language=[[LANGUAGE]] body_text=[[VARIABLE1]] body_text=[[VARIABLE2]]))&\n```\n\n| Parameter name | Parameter description                                                                                                      | Required  |\n|----------------|----------------------------------------------------------------------------------------------------------------------------|-----------|\n| namespace      | Unique code provided by WhatsApp while defining message templates.                                                         | true      |\n| template       | Name of the template provided on WhatsApp Manager.                                                                         | true      |\n| fallback       | We recommend setting the same value as the Template name here.                                                             | true      |\n| language       | The language in which the messages should be sent. The language needs to be defined in the WhatsApp Manager.               | true      |\n| body_text      | The variable text. 0, 1, or multiple variables in a message. Per variable, there needs to be a body_text parameter.        | true      |\n\nThe language codes can be found on: <https://developers.facebook.com/docs/whatsapp/message-templates/creation>\n\nEnterprises construct the messages in shorthand and send it in the text field as shown in the following code.\n\nRequest\n\n```shell\ncurl -X POST https://platform.hootsuite.com/inbox/v1/proactive-messaging/ \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{ \"medium\": \"WHATSAPP\", \"channel\": \"myChannel\", \"contact\": \"+32495123456\", \"text\": \"&((namespace=[[3c860f8b_1ae3_1105_b9ea_647e69aa2d49]] template=[[welcome_customer]] fallback=[[welcome_customer]] language=[[en]] body_text=[[Gregory]] body_text=[[How can I help you?]]))&\" }'\n```\n\nResponse `200`\n\n```json\n{\n  \"correlationId\": \"3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66\"\n}\n```\n\n3. Get status overview\n\nRequest\n\n```shell\ncurl -X GET https://platform.hootsuite.com/inbox/v1/proactive-messaging/3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66 \\\n  -H 'Authorization: Bearer '\n```\n\nResponse `200`\n\n```json\n{\n  \"correlationId\": \"3a7c6c1d-9f9b-11e8-b23b-6f13d5844b66\",\n  \"total\": 1,\n  \"statuses\": {\n    \"SENT\": 1\n  }\n}\n```\n\n4. Get status details\n\nRequest\n\n```shell\ncurl -X GET https://platform.hootsuite.com/inbox/v1/proactive-messaging/f988bd0f-9f9d-11e8-b23b-7d351b0c7ce9/FAILED \\\n  -H 'Authorization: Bearer '\n```\n\nResponse 200\n\n```json\n[\n  {\n    \"status\": \"FAILED\",\n    \"contact\": \"+32495123456\",\n    \"reason\": \"No channel found for medium TWIT\"\n  }\n]\n```\n"
paths:
  /inbox/v1/proactive-messaging:
    post:
      tags:
      - proactive_messaging_rest_api
      summary: Send proactive message
      operationId: proactiveSendMessage
      description: 'The message is queued for processing. Use the returned correlation id to get the status of the sent message.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendProactiveMessageRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendProactiveMessageResponse'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              example:
                errors:
                - 'channel: must not be blank'
                - 'contactReference: must not be blank'
                - 'medium: must not be null'
                - 'text: must not be blank'
        '401':
          description: 'Unauthorized: when using an invalid or expired access token

            '
  /inbox/v1/proactive-messaging/{correlationId}:
    get:
      tags:
      - proactive_messaging_rest_api
      summary: Get status
      operationId: proactiveGetStatusForCorrelationId
      description: 'Get the status overview for a sent proactive message

        '
      parameters:
      - in: path
        name: correlationId
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOverviewResponse'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - Nothing found for this correlation id
        '401':
          description: 'Unauthorized: when using an invalid or expired access token

            '
  /inbox/v1/proactive-messaging/{correlationId}/{status}:
    get:
      tags:
      - proactive_messaging_rest_api
      summary: Get status detail
      operationId: proactiveGetStatusDetailForCorrelationId
      description: 'Get the details of a message with a specific status.

        '
      parameters:
      - in: path
        name: correlationId
        schema:
          type: string
        required: true
      - in: path
        name: status
        schema:
          type: string
          enum:
          - PROCESSING
          - FAILED
          - SENT
          - DELIVERED
          - DELIVERING_FAILED
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusDetailResponse'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - Nothing found for this correlation id
        '401':
          description: 'Unauthorized: when using an invalid or expired access token

            '
components:
  schemas:
    SendProactiveMessageResponse:
      type: object
      properties:
        correlationId:
          type: string
          example: 4f1dba7b-9ef3-11e8-a0f4-175408e41992
    StatusOverviewResponse:
      type: object
      properties:
        correlationId:
          type: string
          description: The correlation id of the sent message.
        total:
          type: string
          description: The total number of sent proactive messages.
        statuses:
          type: object
          description: An overview with the number of messages per status
          properties:
            PROCESSING:
              type: number
              description: Number of proactive messages that are queued for sending.
            FAILED:
              type: number
              description: Number of proactive messages that failed to send.
            SENT:
              type: number
              description: Number of proactive messages that are sent.
            DELIVERED:
              type: number
              description: Number of proactive messages that are sent and delivered.
            DELIVERING_FAILED:
              type: number
              description: Number of proactive messages that are sent but could not be delivered.
      example:
        correlationId: 44717822-9f05-11e8-b71e-671342217f40
        total: 1
        statuses:
          DELIVERED: 1
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    SendProactiveMessageRequest:
      type: object
      properties:
        medium:
          type: string
          description: The medium you want to use
          enum:
          - WHATSAPP
        channel:
          type: string
          description: The name of the channel. Use one of the Accounts in Settings -> Channels
        contact:
          type: string
          description: The reference to a contact. In case of a telephone number it should start with a plus sign
        text:
          type: string
          description: The message you want to send
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            myReference: '19758293529351'
          description: 'When sending a proactive message, you can pass along custom information that is stored in Inbox 2.0. This data can then be exported. Please contact `dev.support@hootsuite.com` to add metadata to the Messages export. For example, when you send an appointment confirmation to your customer, you can pass along a unique identifier. You can then download the Messages export from Inbox 2.0, and determine how many unique customers are responding to your outbound notification.

            '
        sender:
          type: object
          properties:
            pictureUrl:
              type: string
              example: https://example.com/my-picture.png
              description: 'The url of the picture to be used as the sender''s avatar.

                '
      required:
      - medium
      - channel
      - contact
      - text
    StatusDetailResponse:
      type: array
      items:
        type: object
        properties:
          status:
            type: string
            description: The status of the message
          contact:
            type: string
            description: The contact used to send the message to
          reason:
            type: string
            description: The reason of failure
      example:
      - status: FAILED
        contact: '+32495123456'
        reason: No channel found for medium WHATSAPP
  securitySchemes:
    bearer-token:
      type: http
      scheme: bearer
    basic-auth:
      type: http
      scheme: basic
    Oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: TO_BE_CONFIGURED_IN_INBOX_2_0
          scopes:
            some_scope: TO_BE_CONFIGURED_IN_INBOX_2_0
    SharedSecret:
      type: apiKey
      in: header
      name: X-Hootsuite-Signature
x-provenance:
  generated: '2026-08-13'
  method: searched
  source: https://apidocs.hootsuite.com/docs/api/inbox/openapi/openapi.yaml
  note: Verbatim first-party OpenAPI 3.1 for the Hootsuite Inbox 2.0 API (formerly Sparkcentral), linked as service-desc for anchor https://platform.hootsuite.com/inbox/v1/ in Hootsuite's RFC 9727 API catalog at https://www.hootsuite.com/.well-known/api-catalog.
  ownership: servers[] https://platform.hootsuite.com, contact dev.support@hootsuite.com, license "Hootsuite Developer Terms and API License Agreement" - Hootsuite's own contract.
x-tagGroups:
- name: General
  tags:
  - rest-api-authentication
- name: CRM API
  tags:
  - crm_introduction
  - crm_webhooks
  - crm_rest_api
- name: Virtual Agent API
  tags:
  - vai_introduction
  - vai_webhooks
  - vai_rest_api
- name: Real-time metrics API
  tags:
  - real_time_metrics_introduction
  - real_time_metrics_rest_api
- name: User Presence API
  tags:
  - user_presence_introduction
  - user_presence_rest_api
- name: Queue API
  tags:
  - queue_introduction
  - queue_rest_api
- name: Proactive messaging API
  tags:
  - proactive_messaging_introduction
  - proactive_messaging_rest_api
- name: Messenger SDK
  tags:
  - messenger_introduction
  - messenger_web_sdk