openapi: 3.2.0
info:
  title: Sendpulse Chats API
  version: 0.0.1
  description: 'Operations tagged chats across 7 of this provider''s published API definitions: sendpulse-facebook-openapi.yml, sendpulse-instagram-openapi.yml, sendpulse-live-chat-openapi.yml, sendpulse-telegram-openapi.yml, sendpulse-tiktok-openapi.yml, sendpulse-viber-chatbot-openapi.yml, sendpulse-whatsapp-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: ''
  url: https://api.sendpulse.com/messenger
- description: ''
  url: https://api.sendpulse.com/instagram
- description: ''
  url: https://api.sendpulse.com/live-chat
- description: ''
  url: https://api.sendpulse.com/telegram
- description: ''
  url: https://api.sendpulse.com/tiktok
- description: ''
  url: https://api.sendpulse.com/viber/chatbots
- description: ''
  url: https://api.sendpulse.com/whatsapp
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: chats
paths:
  /chats:
    get:
      summary: Get a list of chats
      description: Returns a list of chats with subscribers with information about the contact and the last message received from the contact
      security:
      - oAuth2ClientCredentials: []
      tags:
      - chats
      parameters:
      - in: query
        name: bot_id
        required: true
        schema:
          type: string
        description: Bot ID. Can be obtained with a method of getting a list of bots. You can also find it in your account in the address bar of a chat window with the desired contact.
      - in: query
        name: size
        schema:
          type: integer
      - in: query
        name: skip
        schema:
          type: integer
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Chat'
                type: object
      operationId: getChats
      x-ai-role: chatbot_conversation_analyst
      x-ai-description: Retrieves a paginated list of active chat threads between a bot and its subscribers. Each entry combines contact identity with the most recent inbound message, enabling agents to assess conversation state, prioritize follow-ups, and detect unanswered inquiries across the bot's audience.
      x-ai-reasoning-instructions:
      - Resolve the correct bot_id before calling — it is required and must match an existing bot in the account.
      - Use `skip` and `size` together for pagination; if the user needs all chats, iterate with increasing `skip` until fewer results than `size` are returned.
      - The last message in each chat reflects subscriber-initiated contact — use it to identify open questions or stale conversations requiring a reply.
      - If the user wants chats for a specific contact, filter client-side by contact identifier after fetching, as this endpoint does not support contact-level filtering directly.
      x-ai-responding-instructions:
      - Report how many chats were returned and whether pagination is likely needed (i.e., result count equals `size`).
      - Highlight any chats where the last message appears unanswered or is recent, if that context is relevant to the user's goal.
      - If bot_id is missing or invalid, explain how to retrieve valid bot IDs using the bot listing method.
      x-ai-suggestions:
      - Fetch the first page with size=20 to get an overview before paginating deeper.
      - Combine with the 'send message' endpoint to follow up on specific chats identified here.
      - Use bot_id from the account URL bar if the bot list API is unavailable.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    servers:
    - description: ''
      url: https://api.sendpulse.com/messenger
  /chats/messages:
    get:
      summary: Get a list of messages
      description: Returns a list of all messages in correspondence with the specified subscriber
      security:
      - oAuth2ClientCredentials: []
      tags:
      - chats
      parameters:
      - in: query
        name: contact_id
        required: true
        schema:
          type: string
        description: Contact ID. Can be obtained with a contact search by tag or variable. You can also find it in your account in the address bar of a chat window with the desired contact.
      - in: query
        name: size
        description: The limit of pagination items, that will be returned
        schema:
          type: integer
      - in: query
        name: skip
        description: The offset of pagination items, where starts a current items batch
        schema:
          type: integer
      - in: query
        name: order
        description: Sort order ASC or DESC
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Message'
                type: object
      operationId: getChatMessages
      x-ai-role: customer_communication_analyst
      x-ai-description: Retrieves the full message history of a specific chat thread with a subscriber. This is the primary endpoint for auditing conversations, replaying interaction context before responding, or feeding message history to AI agents that need conversational continuity. The contact_id is the unique thread identifier — without it no messages can be fetched.
      x-ai-reasoning-instructions:
      - Always confirm you have a valid contact_id before calling — it is a required parameter and cannot be inferred from name or email alone.
      - Use 'skip' and 'size' together to paginate large chat histories; avoid fetching everything at once for active, high-volume contacts.
      - Default sort order is unspecified — if you need the most recent messages, explicitly pass order=desc.
      - If building conversational context for an AI response, fetch the last N messages (small 'size', order=desc) rather than the full history.
      x-ai-responding-instructions:
      - Report the number of messages returned and whether pagination was applied.
      - If the result is empty, clarify that this contact exists but has no message history yet.
      - When presenting messages to a user, group them chronologically and distinguish inbound vs outbound direction if present in the schema.
      - Suggest using order=desc with a small size as the efficient pattern for 'show latest messages' requests.
      x-ai-suggestions:
      - 'Fetch the last 20 messages: contact_id=<id>&size=20&order=desc'
      - 'Page through history: contact_id=<id>&size=50&skip=50'
      - After retrieving messages, use the send-message endpoint to continue the conversation
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    servers:
    - description: ''
      url: https://api.sendpulse.com/messenger
  /chats/react:
    put:
      summary: React to a message
      description: Send a reaction (e.g. an emoji) to a specific message of a contact.
      security:
      - oAuth2ClientCredentials: []
      tags:
      - chats
      requestBody:
        description: Choose one of available request body
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message_id
              - reaction
              properties:
                message_id:
                  type: string
                  description: The ID of the message to react to.
                reaction:
                  type: string
                  description: Unicode escape sequence of the emoji, or the emoji itself, to apply to the user message.
                  example: 👍
            examples:
              reaction_example:
                summary: 'Example: send a heart emoji reaction'
                value:
                  message_id: 60f030a0e4a26f4f35399d73
                  reaction: ❤️
      responses:
        '200':
          description: Indicates the reaction was successfully recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: boolean
      operationId: reactToChatMessage
      x-ai-role: chat_engagement_specialist
      x-ai-description: Attaches an emoji reaction to a specific inbound message within a contact's chat thread. Reactions are a lightweight, non-intrusive form of acknowledgment that improve perceived responsiveness without sending a full reply. In conversational CRM workflows, reacting to a message signals to the contact that their message was seen and processed, which can reduce follow-up noise.
      x-ai-reasoning-instructions:
      - Ensure `message_id` refers to an existing message in a chat thread — reactions cannot be applied to system events or outbound messages.
      - Accept both the emoji character directly (e.g., ❤️) and its Unicode escape sequence — validate which form the channel supports if the user is unsure.
      - Prefer using widely-supported single-codepoint emojis (👍, ❤️, 😂) to maximize compatibility across contact devices and chat platforms.
      - Reactions are typically idempotent — applying the same reaction twice usually replaces or removes it; inform the user if toggling behavior is expected.
      - If the goal is to acknowledge a specific customer sentiment, suggest a semantically appropriate emoji rather than a generic one.
      x-ai-responding-instructions:
      - Confirm that the reaction was successfully recorded by referencing the `message_id` used.
      - If `success` is false or `data` is false, explain that the message may not exist, may not support reactions, or the emoji may be unsupported.
      - Suggest a follow-up action if the reaction is part of a larger workflow — e.g., creating a task or sending a reply.
      x-ai-suggestions:
      - Use 👍 to acknowledge a resolved issue without sending an explicit reply.
      - Use ❤️ to confirm receipt of positive customer feedback.
      - Use ✅ to signal that a requested action has been completed.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ResourceStateUpdate
    servers:
    - description: ''
      url: https://api.sendpulse.com/whatsapp
components:
  schemas:
    Contact:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled"
        channel_data:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            first_name:
              type: string
            last_name:
              type:
              - string
              - 'null'
            profile_pic:
              type:
              - string
              - 'null'
            locale:
              type:
              - string
              - 'null'
            gender:
              type:
              - string
              - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        unsubscribed_at:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Chat:
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        inbox_last_message:
          $ref: '#/components/schemas/Message'
        inbox_unread:
          type: integer
    Message:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://developers.facebook.com/docs/messenger-platform/reference/send-api/#message
          example:
            text: hello
        direction:
          type: integer
          enum:
          - 1
          - 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        delivered_at:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        opened_at:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        redirected_at:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Contact_2:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        channel_data:
          type: object
          properties:
            id:
              type: integer
            user_name:
              type:
              - string
              - 'null'
            first_name:
              type: string
            last_name:
              type:
              - string
              - 'null'
            name:
              type: string
            profile_pic:
              type:
              - string
              - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_2:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          description: "\n                    * `1` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Contact_3:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        online:
          type: boolean
        channel_data:
          type: object
          properties:
            id:
              type: integer
            full_name:
              type: string
            url:
              type:
              - string
              - 'null'
              example: null
            lang:
              type:
              - string
              - 'null'
              example: null
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_3:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign:
          type:
          - object
          - 'null'
          example: null
        chain:
          type:
          - object
          - 'null'
          example: null
        reject_reason:
          type:
          - string
          - 'null'
          example: null
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            type: type
            text: hello
            subscriber_id: d86e2ca7-0000-0000-1111-1f1f32d0f0b1
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        type:
          type: string
          enum:
          - text
          - image
          - document
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Contact_4:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        channel_data:
          type: object
          properties:
            username:
              type:
              - string
              - 'null'
            first_name:
              type: string
            last_name:
              type:
              - string
              - 'null'
            name:
              type: string
            language_code:
              type:
              - string
              - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        telegram_id:
          type: string
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_4:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
          - 1
          - 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        sent_by:
          type:
          - object
          - 'null'
          description: Operator data, which send a message
        type:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: "Internal type of message\n\n                    * `1` - 'Internal chat',\n                    * `2` - 'External chat',\n                    * `3` - 'Payment',\n                    * `4` - 'Campaign',\n                    * `5` - 'Operator',\n                    * `6` - 'Operator note',\n                    * `7` - 'Feed comment',\n                "
        channel:
          type: string
          enum:
          - ma
          - ma_chat
          - api
          - rss
          - echo
          - jivo
          - open_ai
          - payment
    Contact_5:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        channel_data:
          type: object
          properties:
            id:
              type: string
            conversation_id:
              type: string
            display_name:
              type: string
            username:
              type: string
            profile_image:
              type:
              - string
              - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_5:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Contact_6:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        channel_data:
          type: object
          properties:
            id:
              type: integer
            name:
              type:
              - string
              - 'null'
            avatar:
              type:
              - string
              - 'null'
            country:
              type: string
            language:
              type: string
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_6:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Contact_7:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: "\n                    * `1` - active\n\n                    * `2` - unsubscribed\n\n                    * `3` - disabled\n\n                    * `4` - blocked by user"
        channel_data:
          type: object
          properties:
            username:
              type:
              - string
              - 'null'
            first_name:
              type: string
            last_name:
              type:
              - string
              - 'null'
            name:
              type: string
            language_code:
              type:
              - string
              - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: string
        variables:
          type: object
          description: 'variable_name: variable_value'
        is_chat_opened:
          type: boolean
        last_activity_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        automation_paused_until:
          type:
          - string
          - 'null'
          example: 2020-12-11 21:00:00+00:00
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Message_7:
      properties:
        id:
          type: string
        contact_id:
          type: string
        bot_id:
          type: string
        campaign_id:
          type:
          - string
          - 'null'
        data:
          type: object
          description: https://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: "\n                    * `1` - in\n\n                    * `2` - out"
        status:
          type: integer
          enum:
          - 1
          description: "\n                    * `1` - new\n\n                    * `2` - sent\n\n                    * `3` - delivered\n\n                    * `4` - opened\n\n                    * `5` - redirected\n\n                    * `6` - rejected"
        is_paid:
          type: boolean
        price_cbp:
          type:
          - object
          - 'null'
          description: Conversation Based Price
          example:
            price: 0.006
            currency: USD
            origin_type: user_initiated
            is_free_conversation: false
            country_code: TR
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Static API Key authentication.  A long-lived token generated manually in the SendPulse account settings.

        '
      x-ai-description: 'Permanent authentication token. Ideal for simple integrations without token refresh logic.

        '
    outh2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides temporary tokens (valid for 1 hour) for enhanced security.

        '
x-refined-from:
- sendpulse-facebook-openapi.yml
- sendpulse-instagram-openapi.yml
- sendpulse-live-chat-openapi.yml
- sendpulse-telegram-openapi.yml
- sendpulse-tiktok-openapi.yml
- sendpulse-viber-chatbot-openapi.yml
- sendpulse-whatsapp-openapi.yml