Hootsuite Vai Rest API

openapi: 3.2.0
info:
  title: Inbox 2.0 API Reference Vai 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: vai_rest_api
  x-displayName: REST API
  description: "If you want to send the replies asynchronously or manipulate the conversation in your fulfillment code, you'll need to\ncall the Virtual Agent REST API. \n\nThe [REST API authentication](#tag/rest-api-authentication) section contains more details on how to authenticate your client. \n"
paths:
  /inbox/v1/virtual-agent/conversations/{conversationId}:
    post:
      tags:
      - vai_rest_api
      summary: Manipulate conversation
      operationId: vaiManipulateConversation
      description: 'This allows you to manipulate the conversation in the same way you would when responding to a webhook request. You can

        send a reply, add a topic, and/or hand off the conversation. Each property in the body is optional. If you only want to

        send a message, you can send `{"sendMessage": {"text": "Hi!"}}`. If you want to apply a topic and complete, but not send

        a message, you can, for example, send `{"applyTopics":["Spam"], "complete": "RESOLVED"}`.


        Note that only topics that match a topic in the platform exactly (case insensitive) will be applied to the conversation.

        Non-existing topics are ignored. Currently, no fuzzy matching will occur and typographical errors will result in a

        non-existing topic.


        The same applies to tags. Only tags that match a tag in the platform exactly (case

        insensitive) will be applied to a specific message. Non-existing tags are ignored. You must specify the `messageId` when using the REST

        API. The `messageId` is part of every `INBOUND_MESSAGE_RECEIVED` event.


        If you want to send an attachment, you must first upload the attachment in a separate

        call (`PUT /inbox/v1/virtual-agent/conversations/{conversationId}/attachments/{filename}`), and then use the file name when

        sending the message (`{"sendMessage": {"attachment": ""}}`).


        If the contact already has a value saved for the attribute definition with a particular alias, the update will be

        ignored. If any of the attribute definitions are configured as CRM lookup values, a CRM lookup is performed after the

        attributes are set. For the best performance, we recommend setting contact attributes along with the response to

        indicate that the conversation is completed. Note that the virtual agent will not receive the new attributes from the

        CRM response until the next `CONVERSATION_STARTED` or `CONVERSATION_DELEGATED` event is received for a conversation with

        a contact.

        '
      parameters:
      - in: path
        name: conversationId
        schema:
          type: string
        required: true
        description: Id of the conversation to manipulate. This can be retrieved from the webhook payload.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationManipulation'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The request is malformed.
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
        '404':
          description: 'The conversation id does not exist or is no longer assigned to the virtual agent.

            '
  /inbox/v1/virtual-agent/conversations/{conversationId}/attachments/{filename}:
    post:
      tags:
      - vai_rest_api
      summary: Upload attachments
      operationId: vaiUploadConversationAttachment
      description: "This allows you to upload an attachment that you can send in a conversation. You need to upload the attachment first,\nand then you can send a message with text and an attachment. For example, if you upload an attachment\nto `/inbox/v1/virtual-agent/conversations/attachments/cat.jpg`, you can send that attachment by sending\n\n```json\n{\n  \"sendMessage\": {\n    \"text\": \"This is a cat!\",\n    \"attachment\": \"cat.jpg\"\n  }\n}\n```\n\nto `/inbox/v1/virtual-agent/conversations/{conversationId}`. The file name should be unique within a conversation and is visible to the contact\nif they download your attachment.\n\nThe `Content-Type` header should contain the correct mime-type of the attachment (such as `image/jpeg`).\nThe `Content-Length` header should contain the size of the attachment in bytes. Attachments should be fewer than 10\nmegabytes to prevent error.\n"
      parameters:
      - in: path
        name: conversationId
        schema:
          type: string
        required: true
        description: ID of the conversation to manipulate. This can be retrieved from the webhook payload.
      - in: path
        name: filename
        schema:
          type: string
        required: true
        description: Filename of the attachment. The filename can only contain uppercase and lowercase letters, numbers, -, _ and .
      - in: header
        name: Content-Type
        schema:
          type: string
        required: true
        description: mime-type of the attachment.
      - in: header
        name: Content-Length
        schema:
          type: string
        required: true
        description: Size of the attachment in bytes.
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: 'The attachment is uploaded and ready to use in your conversation. Note: after uploading the attachment to Inbox 2.0,

            you still need to specifically send it to the contact

            '
          content:
            application/json:
              schema:
                type: object
        '400':
          description: 'The request is malformed. This can happen because the filename contains an invalid character, or because the attachment

            type cannot be sent to the medium.

            '
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
        '404':
          description: 'The conversation id does not exist or is no longer assigned to the virtual agent.

            '
components:
  schemas:
    Message:
      type: object
      properties:
        text:
          type: string
          example: Hi! How can I help you?
        attachment:
          type: string
          example: funny_cat.gif
      description: 'The messages you want to send

        '
    ConversationManipulation:
      type: object
      properties:
        indicateTyping:
          type: string
          enum:
          - START
          - STOP
          description: 'Indicate whether you are typing

            '
        sendMessages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: 'The messages you want to send

            '
        sendMessage:
          $ref: '#/components/schemas/Message'
          description: 'The message you want to send

            '
        applyTopics:
          type: array
          items:
            type: string
          example:
          - Hotel Reservation
          description: 'The topics you want to apply to the conversation

            '
        applyTags:
          type: array
          items:
            type: string
          example:
          - Happy
          description: 'The tag you want to apply to the latest message

            '
        applyConversationNotes:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                example: Some note to add
          description: 'The notes you want to apply to the conversation

            '
        setContactAttributes:
          type: object
          additionalProperties:
            type: string
          example:
            account_number: '19758293529351'
          description: 'The attributes you want to apply to the contact. The key should match "^[a-zA-Z0-9_]+$"

            '
        complete:
          type: string
          enum:
          - HANDOVER
          - RESOLVED
          description: 'Finish a conversation by handing it off to a human agent or by marking the conversation resolved

            '
  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