SendPulse Dialogs API

openapi: 3.2.0
info:
  description: Using the API for Chatbots, you can integrate your system with SendPulse’s chatbots service and get detailed information about your account, bots, dialogs.
  title: Chatbots service Dialogs API
  version: 0.0.1
servers:
- description: ''
  url: https://api.sendpulse.com/chatbots
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: dialogs
paths:
  /dialogs:
    get:
      summary: Get dialogs list info
      description: Returns information about your dialogs from all channels
      security:
      - oAuth2ClientCredentials: []
      tags:
      - dialogs
      parameters:
      - 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: search_after
        description: The id of last_inbox_message.id element after which elements will be searched
        schema:
          type: string
      - 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:
                    type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/Dialog'
                      sort:
                        type: object
                      total:
                        type: integer
                      size:
                        type: integer
                      search_after:
                        type: string
                      order:
                        type: string
                        enum:
                        - asc
                        - desc
                type: object
      operationId: getDialogs
      x-ai-role: omnichannel_support_specialist
      x-ai-description: Retrieves a paginated list of dialogs across all connected messaging channels (Telegram, WhatsApp, Facebook, Instagram, Viber, etc.). A 'dialog' in SendPulse represents a conversation thread between the bot and a specific contact. This endpoint is the primary entry point for inbox management, agent assignment workflows, and CRM-style conversation tracking across all channels simultaneously.
      x-ai-reasoning-instructions:
      - Use `size` to control page volume — default is typically 20; reduce to 10 for faster responses when previewing.
      - For cursor-based pagination, always carry `search_after` from the previous response into the next request instead of using `skip` for large datasets, as it is more performant.
      - 'Combine `order: desc` with `search_after` to stream new incoming dialogs in real time.'
      - If the user asks about a specific channel, note that this endpoint returns all channels — use the returned `Dialog` objects to filter client-side by channel type.
      - When total exceeds size, inform the user that multiple pages exist and offer to iterate.
      x-ai-responding-instructions:
      - Report the total number of dialogs found and how many are returned in the current page.
      - Highlight the `search_after` cursor value if more pages are available, and explain how to use it for the next request.
      - If the list is empty, suggest checking whether any channels are connected in the account.
      - Group or summarize dialogs by channel type when presenting to the user, if the data allows.
      x-ai-suggestions:
      - Use `order=desc` to get the most recently active dialogs first.
      - Use `size=50` for bulk exports, `size=10` for quick inbox previews.
      - Paginate with `search_after` using the last `last_inbox_message.id` from the previous response.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
components:
  schemas:
    Dialog:
      properties:
        _id:
          type: string
        bot_id:
          type: string
        contact:
          type: object
          properties:
            id:
              type: string
            full_name:
              type: string
            profile_pic:
              type: string
        last_inbox_message:
          type: object
          properties:
            text:
              type: string
            date:
              type: string
              example: 2020-12-11 21:00:00+00:00
        last_outbox_message:
          type: object
          properties:
            text:
              type: string
            date:
              type: string
              example: 2020-12-11 21:00:00+00:00
        service:
          type: integer
        user_id:
          type: integer
        inbox_unread_count:
          type: integer
        is_chat_opened:
          type: boolean
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
        updated_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.

        '