SendPulse Bots API

openapi: 3.2.0
info:
  title: Sendpulse Bots API
  version: 0.0.1
  description: 'Operations tagged bots across 4 of this provider''s published API definitions: sendpulse-chatbots-openapi.yml, sendpulse-facebook-openapi.yml, sendpulse-telegram-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/chatbots
- description: ''
  url: https://api.sendpulse.com/messenger
- description: ''
  url: https://api.sendpulse.com/telegram
- description: ''
  url: https://api.sendpulse.com/whatsapp
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Bots
paths:
  /bots:
    get:
      summary: Get a list of connected bots
      description: 'Returns lists of bots with information about each: bot ID, channel information, number of received and unread messages, bot status, and creation date'
      security:
      - oAuth2ClientCredentials: []
      tags:
      - Bots
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bot'
                type: object
      operationId: getBots
      x-ai-role: chatbot_operations_manager
      x-ai-description: Retrieves a full inventory of connected bots across all supported channels (Telegram, WhatsApp, Facebook, etc.). This is the primary discovery endpoint — use it to map available automation assets before routing messages, checking bot health, or selecting a target bot for a campaign. Bot status and unread message counts serve as lightweight health indicators.
      x-ai-reasoning-instructions:
      - Call this endpoint first when the user needs to interact with any bot but hasn't specified a bot ID yet.
      - Filter the result by channel type if the user has specified a platform (e.g., 'my Telegram bots').
      - Check `status` field to warn the user if the target bot is inactive before proceeding with message sending.
      - Use `unread` count to surface bots that may need attention.
      x-ai-responding-instructions:
      - Present bots grouped by channel for clarity if multiple channels are present.
      - Highlight any bots with non-active status and suggest investigating them.
      - If the list is empty, inform the user that no bots are connected and suggest connecting one via the SendPulse dashboard.
      - When the user needs a specific bot, confirm which one to use before proceeding.
      x-ai-suggestions:
      - Use the returned bot `id` with `sendMessage` or `getSubscribers` endpoints.
      - Check `unread` counts to prioritize bots that need follow-up.
      - Cross-reference `created_at` to identify recently added bots.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    servers:
    - description: ''
      url: https://api.sendpulse.com/chatbots
  /bots/statistics:
    get:
      summary: Get general statistics info by bot
      description: Returns general statistics info by bot
      security:
      - oAuth2ClientCredentials: []
      parameters:
      - in: query
        name: bot_id
        required: true
        schema:
          type: string
        description: The 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.
      tags:
      - Bots
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subscribedTotalCount:
                        type: integer
                      subscribedActiveCount:
                        type: integer
                      outgoingMessagesTotalCount:
                        type: integer
      operationId: getBotStatistics
      x-ai-role: chatbot_performance_analyst
      x-ai-description: 'Provides a high-level health snapshot of a specific chatbot: how many users subscribed overall versus how many remain active, and the total volume of outgoing messages. This is the primary diagnostic endpoint for assessing bot engagement quality — a large gap between total and active subscribers signals audience churn or poor re-engagement.'
      x-ai-reasoning-instructions:
      - Ensure the bot_id is valid and belongs to the authenticated account before calling; use the list-bots endpoint if the ID is unknown.
      - 'Treat subscribedActiveCount vs subscribedTotalCount ratio as a health indicator: a ratio below 0.5 warrants a re-engagement campaign recommendation.'
      - outgoingMessagesTotalCount reflects cumulative lifetime messages — do not interpret it as a per-day or per-month metric without additional context from the user.
      x-ai-responding-instructions:
      - Present the active/total subscriber ratio as a percentage to make the insight immediately actionable.
      - If active subscribers are significantly lower than total, proactively suggest reviewing bot flows or launching a re-subscription campaign.
      - Mention the bot_id used in the response so the user can confirm they queried the correct bot.
      x-ai-suggestions:
      - Cross-reference with message delivery stats to understand if low activity correlates with delivery failures.
      - Use this endpoint before launching a broadcast to estimate effective audience size.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    servers:
    - description: ''
      url: https://api.sendpulse.com/messenger
components:
  schemas:
    Bot:
      properties:
        id:
          type: string
        channel_data:
          type: object
          properties:
            access_token:
              type: string
            id:
              type: integer
            name:
              type: string
            username:
              type: string
        inbox:
          type: object
          properties:
            total:
              type: integer
            unread:
              type: integer
        status:
          type: integer
          enum:
          - 3
          - 4
          description: "\n                    * `3` - active\n\n                    * `4` - inactive"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Bot_2:
      properties:
        id:
          type: string
        channel_data:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            photo:
              type:
              - string
              - 'null'
        inbox:
          type: object
          properties:
            total:
              type: integer
            unread:
              type: integer
        status:
          type: integer
          enum:
          - 3
          - 5
          description: "\n                    * `3` - active\n\n                    * `5` - inactive"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Bot_3:
      properties:
        id:
          type: string
        channel_data:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
            username:
              type: string
        inbox:
          type: object
          properties:
            total:
              type: integer
            unread:
              type: integer
        commands_menu:
          type: object
          properties:
            status:
              type: integer
              enum:
              - 1
              - 2
              description: "\n                    * `1` - active\n\n                    * `2` - inactive"
            commands:
              type: array
              items:
                type: object
                properties:
                  description:
                    type:
                    - string
                    - 'null'
                  command:
                    type: string
                  flow_id:
                    type: string
        status:
          type: integer
          enum:
          - 3
          - 4
          description: "\n                    * `3` - active\n\n                    * `4` - inactive"
        created_at:
          type: string
          example: 2020-12-11 21:00:00+00:00
    Bot_4:
      properties:
        id:
          type: string
        channel_data:
          type: object
          properties:
            name:
              type: string
            phone:
              type: integer
        inbox:
          type: object
          properties:
            total:
              type: integer
            unread:
              type: integer
        status:
          type: integer
          enum:
          - 3
          - 4
          description: "\n                    * `3` - active\n\n                    * `4` - inactive"
        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-chatbots-openapi.yml
- sendpulse-facebook-openapi.yml
- sendpulse-telegram-openapi.yml
- sendpulse-whatsapp-openapi.yml
x-provenance:
  method: harvested
  publisher: SendPulse
  source: https://api.sendpulse.com/.well-known/openapi/telegram.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)