components:
  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.
  schemas:
    SuccessResponse:
      properties:
        success:
          type: boolean
        data:
          anyOf:
            - type: array
              items:
                type: object
            - type: object
            - type: boolean
      type: object
    Account:
      properties:
        plan:
          type: object
          description: '`-1` - unlimited'
          properties:
            code:
              type: string
            max_bots:
              type: integer
            max_contacts:
              type: integer
              example: -1
            max_messages:
              type: integer
            max_tags:
              type: integer
            max_variables:
              type: integer
            branding:
              type: boolean
            is_exceeded:
              type: boolean
            is_expired:
              type: boolean
            expired_at:
              type: string
              example: 2020-12-11T21:00:00.000Z
        statistics:
          type: object
          description: ''
          properties:
            messages:
              type: integer
            bots:
              type: integer
            contacts:
              type: integer
            variables:
              type: integer
    Bot:
      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: |2-

                                * `3` - active

                                * `4` - inactive
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Contact:
      properties:
        id:
          type: string
        bot_id:
          type: string
        status:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: |2-

                                * `1` - active

                                * `2` - unsubscribed

                                * `3` - disabled

                                * `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-11T21:00:00.000Z
        automation_paused_until:
          type:
            - string
            - 'null'
          example: 2020-12-11T21:00:00.000Z
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Variable:
      properties:
        id:
          type: string
        bot_id:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        type:
          type: integer
          enum:
            CONTACT: 1
          description: |2-

                                * `1` - contact variable

                                * `2` - bot variable
        value_type:
          type: integer
          example: 1
          enum:
            STRING: 1
            NUMBER: 2
            DATE: 3
            BOOLEAN: 4
            PHONE: 5
            EMAIL: 6
            URL: 7
            LOCATION: 8
            DATETIME: 9
            TIME: 10
          description: |2-

                            this type of variable can have the following values:

                                * `1` - string

                                * `2` - number

                                * `3` - date

                                * `4` - boolean

                                * `5` - phone

                                * `6` - email

                                * `7` - url
        status:
          type: integer
          enum:
            ACTIVE: 1
            TRASHED: 2
          description: |2-

                                * `1` - active

                                * `2` - trashed
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Flow:
      properties:
        id:
          type: string
        bot_id:
          type: string
        name:
          type: string
        status:
          type: integer
          enum:
            - ACTIVE: 1
              INACTIVE: 2
              DRAFT: 4
          description: |2-

                                * `1` - active

                                * `2` - inactive
        triggers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: integer
                enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                description: |2-

                                      * `1` - starts immediately upon subscription

                                      * `2` - starts when unsubscribed

                                      * `3` - default reply

                                      * `4` - starts when the specified keyword is entered

                                      * `5` - starts at the specified time when subscribing
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Trigger:
      properties:
        id:
          type: string
        bot_id:
          type: string
        flow_id:
          type:
            - string
            - 'null'
        name:
          type: string
        type:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          description: |2-

                                * `1` - starts immediately upon subscription

                                * `2` - starts when unsubscribed

                                * `3` - default reply

                                * `4` - starts when the specified keyword is entered

                                * `5` - starts at the specified time when subscribing
        status:
          type: integer
          enum:
            ACTIVE: 1
            INACTIVE: 2
          description: |2-

                                * `1` - active

                                * `2` - inactive
        keywords:
          type: array
          items:
            type: string
        execution:
          type: object
          properties:
            interval:
              type: integer
            units:
              type: integer
              enum:
                MINUTES: 1
                HOURS: 2
                DAYS: 3
              description: |2-

                                        * `1` - minutes

                                        * `2` - hours

                                        * `3` - days
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Campaign:
      properties:
        id:
          type: string
        bot_id:
          type: string
        title:
          type: string
        send_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
        messages:
          type: array
          items:
            type: object
        cost:
          type: object
          properties:
            amount:
              type: number
              example: 0.56
            currency:
              type: string
              example: USD
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    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://core.telegram.org/bots/api#message
          example:
            text: hello
        direction:
          type: integer
          enum:
            IN: 1
            OUT: 2
          description: |2-

                                * `1` - in

                                * `2` - out
        status:
          type: integer
          enum:
            - 1
          description: |2-

                                * `1` - new

                                * `2` - sent

                                * `3` - delivered

                                * `4` - opened

                                * `5` - redirected

                                * `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-11T21:00:00.000Z
    Template:
      properties:
        id:
          type: string
        bot_id:
          type: string
        namespace:
          type: string
        category:
          type: string
        components:
          type: array
          description: >-
            Please see
            https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/media-message-templates/
          items:
            type: object
        language:
          type: string
        name:
          type: string
        rejected_reason:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - APPROVED
            - IN_APPEAL
            - PENDING
            - REJECTED
            - PENDING_DELETION
            - DELETED
            - DISABLED
            - PAUSED
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
    Tag:
      properties:
        id:
          type: string
        name:
          type: string
        contact_count:
          type: integer
        created_at:
          type: string
          example: 2020-12-11T21:00:00.000Z
info:
  description: >-
    Using the API for WhatsApp chatbots, you can integrate your system with
    SendPulse’s chatbots service and get detailed information about your
    account, bots, subscribers, variables, flows, and chats. You can also create
    campaigns, launch flows, assign and remove variables and tags.

                
    On the right, there is a button for authorizing requests made on this page.
    Click “Authorize,” then insert the ID and Secret from your account.

                
    To perform a request directly from the page, click the "Try it out" button
    within each method block. Then fill in input fields if any (for URL
    parameters, the description is right below the URL request; for body
    parameters, the description is under the “Scheme” button to the right of the
    example), and click “Run.” You'll find the server response and description
    of received parameters below.
            
  title: WhatsApp service API
  version: 0.0.1
openapi: 3.1.2
paths:
  /contacts:
    post:
      summary: Create new contact
      description: Creates a new contact in the audience of the selected bot
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                phone:
                  type: string
                  description: Phone number in international format
                name:
                  type: string
                  description: Contact name
                bot_id:
                  type: string
                  description: Bot's ID to which you add a contact
                tags:
                  type: array
                  description: List of tags to assign to the contact
                  items:
                    type: string
                variables:
                  type: array
                  description: >-
                    The set of additional parameters differs depending on the
                    included template components and can include variables, an
                    image, or a file.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the variable
                      value:
                        OneOf:
                          - type: string
                            description: The value that is set for the variable
                          - type: integer
                            description: The value that is set for the variable
              required:
                - phone
                - bot_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Contact'
                type: object
      operationId: createContact
      x-ai-role: chatbot_audience_manager
      x-ai-description: >-
        Registers a new contact in the bot's audience, establishing the
        foundational subscriber record. In SendPulse, a contact is not merely a
        phone number — it is a stateful entity tied to a specific bot, enriched
        with tags and custom variables that drive personalization, segmentation,
        and automated flow targeting.
      x-ai-reasoning-instructions:
        - >-
          Always confirm the bot_id exists and belongs to the user's account
          before attempting to create a contact.
        - >-
          Phone number must be in international format (e.g., +14155552671) —
          validate the format before submission.
        - >-
          Check whether a contact with the same phone number already exists in
          the specified bot's audience to avoid duplicates.
        - >-
          If tags are provided, ensure they follow the bot's existing tag
          taxonomy for consistent segmentation.
        - >-
          Variables should be validated against the bot's defined variable
          schema — mismatched names will be silently ignored.
      x-ai-responding-instructions:
        - >-
          Confirm successful creation by referencing the new contact's ID from
          the returned Contact object.
        - >-
          If the phone number is already registered in that bot's audience,
          clarify whether an update or merge is needed instead.
        - >-
          Suggest assigning the contact to a flow or sending an initial message
          as the logical next step.
        - >-
          If creation fails due to bot_id not found, prompt the user to retrieve
          available bots first.
      x-ai-suggestions:
        - >-
          After creation, use `sendMessage` or trigger a flow to engage the
          contact immediately.
        - >-
          Use tags like 'new_lead', 'vip', or 'opt-in-web' for downstream
          segmentation.
        - >-
          Store CRM identifiers in variables (e.g., `crm_id`) to link contacts
          across systems.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - PII
            - ResourceStateUpdate
  /contacts/get:
    get:
      summary: Get contact info via a contact ID
      description: >-
        Returns information on the selected contact: bot and contact ID,
        information from messenger, list of tags and variables, activity data
        and date added
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: 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.
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Contact'
                type: object
      operationId: getContactById
      x-ai-role: crm_data_analyst
      x-ai-description: >-
        Retrieves a complete profile snapshot of a single bot contact —
        including messenger metadata, tags, variables, and engagement history.
        This is the primary lookup endpoint when you need to inspect or verify a
        contact's current state before triggering personalized flows or
        debugging delivery issues.
      x-ai-reasoning-instructions:
        - >-
          Ensure the contact ID is valid and was obtained via a tag/variable
          search or directly from the account UI — do not guess IDs.
        - >-
          Note that this endpoint returns bot-context data (messenger fields,
          activity), not email subscriber data — use the appropriate address
          book endpoints for email contacts.
        - >-
          If the goal is bulk lookup, consider whether a search-by-tag endpoint
          would be more efficient than repeated single-contact calls.
      x-ai-responding-instructions:
        - >-
          Highlight the contact's bot ID and messenger-side ID so the user can
          correlate them across systems.
        - >-
          Surface any tags and variables present on the contact, as these are
          typically what downstream automation logic depends on.
        - >-
          If the contact is not found or the ID is invalid, explain how to
          obtain a valid contact ID (tag search, variable search, or account
          UI).
      x-ai-suggestions:
        - >-
          Use the returned tags and variables to decide which message flow or
          segment this contact belongs to.
        - >-
          After inspecting the contact, consider `updateContactVariables` or
          `addTagToContact` as follow-up actions.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/getByPhone:
    get:
      summary: Get contact info by phone number
      description: >-
        Returns information on the selected contact: bot and contact ID,
        information from messenger, list of tags and variables, activity data
        and date added
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: phone
          required: true
          schema:
            type: string
          description: Contact's phone number in international format.
        - 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.
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Contact'
                type: object
      operationId: getContactByPhone
      x-ai-role: chatbot_crm_specialist
      x-ai-description: >-
        Retrieves a full contact profile by phone number within a specific bot
        context. This is the primary lookup method when you have a phone number
        but not a contact ID — useful for deduplication, pre-flight checks
        before sending messages, or enriching external CRM records with
        SendPulse messenger data.
      x-ai-reasoning-instructions:
        - >-
          Phone number must be in international format (e.g., +14155552671).
          Validate or normalize the format before calling.
        - >-
          bot_id is mandatory — the same phone number may exist in multiple bots
          as separate contacts. Always confirm which bot context is relevant.
        - >-
          Use this endpoint to check if a contact exists before attempting to
          create or message them.
        - >-
          If the contact is not found, consider using the list contacts endpoint
          to verify bot_id correctness before assuming the contact is absent.
      x-ai-responding-instructions:
        - >-
          Surface the contact ID and bot ID from the response — these are
          required for follow-up operations like sending messages or updating
          variables.
        - >-
          Highlight any tags or variables returned, as they often reveal the
          contact's segment or funnel stage.
        - >-
          If activity data is present, summarize recency to help the user assess
          contact engagement.
        - >-
          If the call fails due to a missing contact, suggest verifying the
          phone format or checking the correct bot_id.
      x-ai-suggestions:
        - >-
          Use the returned contact ID with `sendMessage` to initiate a
          conversation.
        - >-
          Check returned variables to determine if contact data needs updating
          before outreach.
        - >-
          Cross-reference activity data with campaign timing to avoid messaging
          inactive contacts.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/getByTag:
    get:
      summary: Get a list of contacts by tag
      description: Returns a list of contacts by tag for the specified bot
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: tag
          required: true
          schema:
            type: string
          description: Created contact’s tag to search by
        - 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
          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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                type: object
      operationId: getContactsByTag
      x-ai-role: chatbot_audience_analyst
      x-ai-description: >-
        Retrieves a filtered subset of bot contacts based on a specific tag.
        Tags in SendPulse chatbots act as behavioral or segmentation labels —
        this endpoint is the primary way to build targeted audiences for
        broadcasts or automations without exporting the full contact list.
      x-ai-reasoning-instructions:
        - >-
          Confirm the bot_id is valid and accessible before querying — contacts
          are bot-scoped and do not span across bots.
        - >-
          Tags are case-sensitive; advise the user to verify exact tag spelling
          if results are unexpectedly empty.
        - >-
          Use `size` and `skip` for pagination when the contact base is large —
          default limits may truncate results silently.
        - >-
          If the goal is a broadcast or automation, note that this endpoint is
          read-only — the result must be fed into a separate send or segment
          operation.
      x-ai-responding-instructions:
        - >-
          Report the total number of contacts returned and clarify if pagination
          was applied.
        - >-
          If the result is empty, suggest checking tag spelling or listing
          available tags via a discovery endpoint.
        - >-
          When results are used for targeting, recommend confirming the segment
          size before initiating a broadcast.
      x-ai-suggestions:
        - >-
          Use `size=100&skip=0` as a starting pagination window for large
          audiences.
        - >-
          Combine with a send-message endpoint to create a targeted campaign for
          this tag segment.
        - >-
          Cross-reference with `getContactsByVariable` if tag-based filtering
          returns insufficient granularity.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/getByVariable:
    get:
      summary: Get contacts by variable
      description: >-
        Returns contacts by variable identifier or variable name for the
        specified bot
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: variable_id
          schema:
            type: string
          description: >-
            Contact’s variable ID to search by; required parameter if you do not
            pass variable_name and bot_id.
        - in: query
          name: variable_name
          schema:
            type: string
          description: >-
            Contact’s variable name to search by; required parameter and passed
            with the bot_id parameter, if you do not pass variable_id.
        - in: query
          name: bot_id
          schema:
            type: string
          description: >-
            Bot ID; required parameter and passed with the variable_name
            parameter, if you do not pass variable_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: variable_value
          required: true
          schema:
            type: string
          description: Contact's variable value
        - 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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                type: object
      operationId: getContactsByVariable
      x-ai-role: chatbot_crm_analyst
      x-ai-description: >-
        Retrieves a filtered list of bot contacts based on a specific CRM
        variable value. This is a targeted lookup mechanism — instead of
        fetching all contacts, it allows precise segmentation by variable (e.g.,
        'plan=premium', 'city=Kyiv'). Supports two resolution paths: by global
        variable_id alone, or by variable_name scoped to a specific bot_id.
      x-ai-reasoning-instructions:
        - >-
          Determine which lookup path to use: if variable_id is known, use it
          alone; if only variable_name is known, require bot_id alongside it.
        - >-
          Never pass both variable_id and variable_name together — resolve the
          ambiguity before calling.
        - >-
          Validate that variable_value is non-empty; an empty string will match
          incorrectly or return no results.
        - >-
          Use size and skip parameters for large result sets to avoid
          overwhelming downstream consumers.
        - >-
          If bot_id is needed but unknown, suggest fetching it via the
          list-of-bots endpoint first.
      x-ai-responding-instructions:
        - Report how many contacts matched, not just whether the call succeeded.
        - >-
          If the result is empty, suggest verifying the variable_value casing or
          checking if the variable exists for that bot.
        - >-
          If paginating, remind the user to increment skip by size to fetch the
          next batch.
        - >-
          Surface contact IDs from the response as the primary next-step input
          for further operations (e.g., sending a message).
      x-ai-suggestions:
        - >-
          Use variable_id when available — it is bot-agnostic and more stable
          than variable_name.
        - Combine with pagination (size=50, skip=0) for large contact bases.
        - >-
          Typical variable_value examples: 'premium', 'true', 'ua',
          '2024-cohort'.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/mark-read:
    put:
      summary: Mark messages as read
      description: Mark contact all messages as read (set unread count 0)
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: contact_id
          schema:
            type: string
          description: Contact’s ID for set unread count as 0
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  count:
                    type: integer
                    description: Contact messages count marked as read
                type: object
      operationId: markContactMessagesAsRead
      x-ai-role: customer_support_specialist
      x-ai-description: >-
        Resets the unread message counter for a specific contact to zero,
        signaling that all incoming messages have been reviewed. This is a
        lightweight status update used to keep inbox state synchronized across
        agents and operators — critical for accurate workload tracking and SLA
        compliance in support workflows.
      x-ai-reasoning-instructions:
        - >-
          Verify that the contact_id is valid and belongs to an active contact
          before calling this endpoint.
        - >-
          Use this endpoint after programmatically processing or reviewing
          messages, not just to suppress notification badges.
        - >-
          If the count returned is 0, the contact likely had no unread messages
          — confirm whether the call was necessary.
      x-ai-responding-instructions:
        - >-
          Confirm success by reporting how many messages were marked as read
          (the `count` field).
        - >-
          If count is 0, inform the user that the contact had no unread
          messages.
        - >-
          Suggest following up with a contact details fetch or reply action as
          the next logical step.
      x-ai-suggestions:
        - >-
          Call this after reading or processing incoming messages to keep unread
          counters accurate.
        - >-
          Use in automation flows after an AI agent handles a contact's
          conversation.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/mark-unread:
    put:
      summary: Mark a chat with the contact as unread
      description: Marks the last message of a specific contact as unread.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      parameters:
        - in: query
          name: contact_id
          schema:
            type: string
          description: The ID of the contact whose last message will be marked as unread.
      responses:
        '200':
          description: The number of messages successfully marked as unread.
          content:
            application/json:
              schema:
                properties:
                  count:
                    type: integer
                    example: 1
                    description: api.paths.contacts.mark-unread.responses.properties.count
                type: object
      operationId: markContactChatUnread
      x-ai-role: customer_support_specialist
      x-ai-description: >-
        Marks the last message of a contact as unread, effectively flagging the
        conversation for follow-up. This is a workflow management operation used
        by support agents to ensure no conversation is accidentally dismissed —
        marking a chat unread signals to the team that it requires attention or
        a response.
      x-ai-reasoning-instructions:
        - >-
          Confirm that the contact_id is valid and the contact exists before
          making the request.
        - >-
          This operation marks only the last message as unread — clarify to the
          user that it does not bulk-mark the entire conversation history.
        - >-
          Use this when an agent wants to re-queue a conversation for review
          without manually assigning it.
      x-ai-responding-instructions:
        - >-
          Confirm success by reporting the value of 'count' (expected: 1)
          returned in the response.
        - >-
          If count is 0, inform the user that no messages were updated — the
          contact may have no messages or already be in unread state.
        - >-
          Suggest following up with a contact details fetch or inbox listing to
          verify the updated state.
      x-ai-suggestions:
        - >-
          Use after reviewing a message to re-flag it for a colleague's
          attention.
        - >-
          Combine with inbox listing to identify all unread conversations
          needing follow-up.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/send:
    post:
      summary: Send a message to a contact
      description: >-
        Sends a text message, image, or a file to contact with the specified
        contact ID. To view an example of the request body, select a message
        type from the drop-down list. 

         You can also use the original data structures specified in Meta\'s documentation https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages by specifying the correct 'type' and the corresponding data structure for that type.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                message:
                  type: object
                  description: >-
                    Message to send, specifying the type and content of the
                    campaign
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - image
                        - document
                        - audio
                        - interactive
                        - reaction
                      description: >-
                        Message type, can have the values "text," "image," or
                        "document"
                      example: text
                    text:
                      type: object
                      properties:
                        body:
                          type: string
                          description: >-
                            The content of the text message. You can add text
                            with emoji of up to 1024 unicode characters.
                      required:
                        - body
                    image:
                      type: object
                      description: >-
                        The image you want to send. Includes the URL to the
                        image and caption
                      properties:
                        link:
                          type: string
                          description: >-
                            Full URL of the image you want to send, including
                            the "https" protocol part. You can only send links
                            to SSL-secured sites
                        caption:
                          type:
                            - string
                            - 'null'
                          description: Caption for the image
                      required:
                        - link
                    file:
                      type: object
                      description: >-
                        The file you want to send. Includes the URL to the image
                        and caption
                      properties:
                        link:
                          type: string
                          description: >-
                            Full URL of the file you want to send, including the
                            "https" protocol part. You can only send links to
                            SSL-secured sites
                        caption:
                          type:
                            - string
                            - 'null'
                          description: Caption for the image
                      required:
                        - link
                    audio:
                      type: object
                      description: >-
                        The audio you want to send. Includes the URL to the
                        audio
                      properties:
                        link:
                          type: string
                          description: >-
                            Full HTTPS URL of the audio file you want to send.
                            Only SSL-secured links are allowed.
                        voice:
                          type: boolean
                          default: false
                          description: >-
                            Indicates that the audio should be sent as a voice
                            message
                      required:
                        - link
                    interactive:
                      type: object
                      description: >-
                        The interactive object you want to send. Includes the
                        buttons and text
                      properties:
                        type:
                          type: string
                          enum:
                            - button
                        body:
                          type: string
                          description: >-
                            The content of the text message. You can add text
                            with emoji of up to 1024 unicode characters.
                        action:
                          type: object
                          properties:
                            buttons:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - reply
                                  to_chain_id:
                                    type: string
                                  reply:
                                    types: object
                                    properties:
                                      title:
                                        type: string
                    reaction:
                      type: object
                      description: Reaction to a message
                      properties:
                        message_id:
                          type: string
                          description: ID of the message to react to
                        emoji:
                          type: string
                          description: Reaction emoji
                      required:
                        - message_id
                        - emoji
                  required:
                    - type
              required:
                - contact_id
                - message
            examples:
              Send a text message:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: text
                    text:
                      body: string
              Send a message with an image:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: image
                    image:
                      link: string
                      caption: string
              Send a message with a file:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: document
                    document:
                      link: string
                      caption: string
              Send a message with an audio:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: audio
                    audio:
                      link: string
                      voice: bool
              Send a message with payload button:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: interactive
                    interactive:
                      type: button
                      body:
                        text: Example text
                      action:
                        buttons:
                          - type: reply
                            to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
                            reply:
                              title: Example payload button
              Send a reaction:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  message:
                    type: reaction
                    reaction:
                      message_id: xxxxxxxxxxxxxxxxxxxxxxxx
                      emoji: 👍
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Message'
                type: object
      operationId: sendContactMessage
      x-ai-role: whatsapp_messaging_specialist
      x-ai-description: >-
        Delivers a direct message to a specific WhatsApp contact within
        SendPulse. This is a one-on-one outreach operation — not a broadcast —
        used for support responses, transactional confirmations, or personalized
        follow-ups. The endpoint is a facade over Meta's Cloud API, so both
        native SendPulse message structures and raw Meta payloads are accepted.
        Choosing the right message type (text vs. interactive vs. reaction)
        significantly affects engagement and bot flow continuation.
      x-ai-reasoning-instructions:
        - >-
          Resolve the contact_id before calling — use contact search by tag or
          variable if only a name or phone is known.
        - >-
          Match the message type to the use case: use 'text' for simple replies,
          'interactive' with buttons to continue a bot flow (to_chain_id),
          'reaction' to acknowledge a specific message, and
          'image'/'document'/'audio' for media delivery.
        - >-
          For 'image', 'document', and 'audio' types, verify the URL is HTTPS
          and publicly accessible before sending; Meta rejects non-SSL or
          private links.
        - >-
          When sending 'audio' with voice: true, ensure the file is in a format
          supported as a voice message (e.g., OGG/OPUS); generic MP3 links may
          be rejected.
        - >-
          For 'interactive' type with buttons, each button must have a valid
          to_chain_id pointing to an existing bot flow chain; invalid chain IDs
          will silently break the flow.
        - >-
          The 'reaction' type requires a valid message_id from the conversation
          history — it cannot be used to react to your own outgoing messages in
          all contexts.
        - >-
          If the user provides raw Meta API structures not covered by the
          schema's enum, remind them these are passthrough-supported but not
          validated by SendPulse.
      x-ai-responding-instructions:
        - >-
          Confirm success by noting the message type sent and the target
          contact_id.
        - >-
          If the response includes a Message object, surface the message ID for
          potential follow-up use (e.g., reacting to this message later).
        - >-
          For 'interactive' messages, mention that the contact's button tap will
          trigger the linked bot chain (to_chain_id).
        - >-
          On failure, distinguish between contact resolution errors (wrong
          contact_id) and delivery errors (bad URL, unsupported format, Meta API
          rejection).
        - >-
          Suggest logical next steps: checking delivery status, sending a
          follow-up, or branching the bot flow based on response.
      x-ai-suggestions:
        - 'Send a quick text reply to a support inquiry using type: text'
        - 'Send an image with a promo caption using type: image'
        - >-
          Present reply buttons to guide the contact through a bot flow using
          type: interactive
        - >-
          React to a contact's message with an emoji acknowledgement using type:
          reaction
        - 'Send a voice message by setting audio.voice: true'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ExternalDelivery
            - ContactDataAccess
          notes: >-
            Message is delivered via Meta's WhatsApp Cloud API. Ensure contact
            has opted in to receive messages to comply with WhatsApp Business
            Policy and applicable data protection regulations.
  /contacts/sendByPhone:
    post:
      summary: Send a free message to a contact by phone number
      description: >-
        Sends a message to the active contact with the specified phone number.
        You can send a text message, an image, or a file. To view an example of
        the request body, select a message type from the drop-down list
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                bot_id:
                  type: string
                  description: >-
                    Bot ID to whose audience you are sending a message. 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.
                phone:
                  type: string
                  example: '380631112233'
                  description: Contact's phone number in international format.
                message:
                  type: object
                  description: >-
                    Message to send, specifying the type and content of the
                    campaign
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - image
                        - document
                        - audio
                      description: >-
                        Message type, can have the values "text," "image," or
                        "document"
                      example: text
                    text:
                      type: object
                      properties:
                        body:
                          type: string
                          description: >-
                            The content of the text message. You can add text
                            with emoji of up to 1024 unicode characters.
                      required:
                        - body
                    image:
                      type: object
                      description: >-
                        The image you want to send. Includes the URL to the
                        image and caption
                      properties:
                        link:
                          type: string
                          description: >-
                            Full URL of the image you want to send, including
                            the "https" protocol part. You can only send links
                            to SSL-secured sites
                        caption:
                          type:
                            - string
                            - 'null'
                          description: Caption for the image
                      required:
                        - link
                    file:
                      type: object
                      description: >-
                        The file you want to send. Includes the URL to the image
                        and caption
                      properties:
                        link:
                          type: string
                          description: >-
                            Full URL of the file you want to send, including the
                            "https" protocol part. You can only send links to
                            SSL-secured sites
                        caption:
                          type:
                            - string
                            - 'null'
                          description: Caption for the image
                      required:
                        - link
                    audio:
                      type: object
                      description: >-
                        The audio you want to send. Includes the URL to the
                        audio
                      properties:
                        link:
                          type: string
                          description: >-
                            Full HTTPS URL of the audio file you want to send.
                            Only SSL-secured links are allowed.
                        voice:
                          type: boolean
                          default: false
                          description: >-
                            Indicates that the audio should be sent as a voice
                            message
                      required:
                        - link
                    interactive:
                      type: object
                      description: >-
                        The interactive object you want to send. Includes the
                        buttons and text
                      properties:
                        type:
                          type: string
                          enum:
                            - button
                        body:
                          type: string
                          description: >-
                            The content of the text message. You can add text
                            with emoji of up to 1024 unicode characters.
                        action:
                          type: object
                          properties:
                            buttons:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - reply
                                  to_chain_id:
                                    type: string
                                  reply:
                                    types: object
                                    properties:
                                      title:
                                        type: string
                  required:
                    - type
              required:
                - bot_id
                - phone
                - message
            examples:
              Send a text message:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  message:
                    type: text
                    text:
                      body: string
              Send a message with an image:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  message:
                    type: image
                    image:
                      link: string
                      caption: string
              Send a message with a file:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  message:
                    type: document
                    document:
                      link: string
                      caption: string
              Send a message with an audio:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  message:
                    type: audio
                    audio:
                      link: string
                      voice: bool
              Send a message with payload button:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  message:
                    type: interactive
                    interactive:
                      type: button
                      body:
                        text: Example text
                      action:
                        buttons:
                          - type: reply
                            to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
                            reply:
                              title: Example payload button
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Message'
                type: object
      operationId: sendMessageToContactByPhone
      x-ai-role: chatbot_messaging_specialist
      x-ai-description: >-
        Sends a direct outbound message to a WhatsApp contact identified by
        phone number within a specific bot's audience. Unlike campaign-based
        sending, this endpoint targets an individual active contact in real
        time, supporting rich media formats (text, image, document, audio) and
        interactive button messages. Use this for personalized outreach,
        transactional notifications, or agent-initiated conversations outside of
        automated flows.
      x-ai-reasoning-instructions:
        - >-
          Verify that the contact with the given phone number exists and is
          active in the specified bot's audience before sending — inactive or
          non-subscribed contacts will cause the request to fail.
        - >-
          Ensure the phone number is in E.164 international format (e.g.,
          '380631112233'), without '+', spaces, or dashes.
        - >-
          Match the `message.type` value to the corresponding nested object:
          'text' requires `text.body`, 'image' requires `image.link`, 'document'
          requires `file.link`, 'audio' requires `audio.link`.
        - >-
          For image, document, and audio types, the URL must be HTTPS — plain
          HTTP links are rejected by the API.
        - >-
          When sending an audio message, set `voice: true` only if the audio
          should appear as a voice note in the chat UI.
        - >-
          For interactive messages, each button must have a `to_chain_id`
          pointing to a valid bot chain/flow node; confirm the chain exists
          before use.
        - >-
          Confirm the `bot_id` belongs to the account and is a WhatsApp bot —
          this endpoint is WhatsApp-specific.
      x-ai-responding-instructions:
        - >-
          On success, confirm the message was delivered and mention the message
          type sent (e.g., 'Text message sent to +380631112233').
        - >-
          If the contact was not found or is inactive, explain that the contact
          must have previously opted in via the bot.
        - >-
          If a media URL was rejected, advise the user to check that it is
          publicly accessible over HTTPS.
        - >-
          Suggest follow-up actions such as tracking delivery status or
          triggering an automation flow as a next step.
        - >-
          If an interactive message was sent, mention that the user's button tap
          will trigger the linked chain.
      x-ai-suggestions:
        - Use 'text' type for simple notifications or confirmations.
        - >-
          Use 'image' type to send product photos, receipts, or visual
          instructions.
        - Use 'document' type for sending invoices, PDFs, or forms.
        - Use 'audio' with voice:true for voice memo-style messages.
        - >-
          Use 'interactive' with reply buttons to guide the contact to a
          specific chatbot flow.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            You are about to send a direct message to a real contact on
            WhatsApp. Confirm before proceeding.
        security_info:
          data_handling:
            - ExternalMessageDelivery
            - PersonalDataTransmission
          notes: >-
            Phone numbers are PII. Ensure the contact has opted in to receive
            messages via this bot to comply with WhatsApp policy and GDPR.
  /contacts/sendTemplate:
    post:
      summary: Send a template message to the specified contact
      description: >-
        Sends a pre-approved template message to the contact with the specified
        contact ID. You can send a template with variables, buttons, image, or
        document headers. To view an example of the request body, select a
        message template from the drop-down list.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: >-
          Sends a pre-approved template message to the contact with the
          specified contact ID. You can send a template with variables, buttons,
          image, or document headers. To view an example of the request body,
          select a message template from the drop-down list.
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                template:
                  type: object
                  description: >-
                    Content of the template. To get a template code in your
                    account, go to the "Templates" tab of your bot and, opposite
                    the desired template, click "Copy code." In the opened
                    window, copy the value of the "template" parameter.
                  properties:
                    name:
                      type: string
                      example: event_started
                      description: Template name
                    language:
                      type: object
                      description: Template language
                      properties:
                        code:
                          type: string
                          example: en
                      required:
                        - code
                    components:
                      type: array
                      description: >-
                        The set of additional parameters differs depending on
                        the included template components and can include
                        variables, an image, or a file.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: >-
                              Accepted values: header / body / footer depending
                              on where you want to insert the component
                          sub_type:
                            type: string
                            description: >-
                              Accepted values: url / quick_reply / catalog.
                              Required when type=button. Not used for the other
                              types. Type of button to create
                          index:
                            type: int
                            description: >-
                              Required when type=button. Not used for the other
                              types. Position index of the button. You can have
                              up to 3 buttons using index values of 0 to 2.
                          parameters:
                            type: array
                            description: >-
                              Сustom template variables. Specify the type, name
                              and value of the variable
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                  description: Variable type
                                image:
                                  type: object
                                  description: >-
                                    The image you want to send. Includes the URL
                                    to the image and caption
                                  properties:
                                    link:
                                      type: string
                                      description: >-
                                        Full URL of the file you want to send,
                                        including the "https" protocol part. You
                                        can only send links to SSL-secured sites
                                video:
                                  type: object
                                  description: >-
                                    The video you want to send. Includes the URL
                                    to the video file.
                                  properties:
                                    link:
                                      type: string
                                      description: >-
                                        Full URL of the file you want to send,
                                        including the "https" protocol part. You
                                        can only send links to SSL-secured sites
                                payload:
                                  type: object
                                  description: >-
                                    Required for quick_reply buttons.
                                    Developer-defined payload that is returned
                                    when the button is clicked in addition to
                                    the display text on the button.
                                  properties:
                                    to_chain_id:
                                      type: string
                  required:
                    - name
                    - language
              required:
                - contact_id
                - template
            examples:
              Send a simple template message:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying
                    language:
                      code: en
                    components: []
              Send a template message with variables:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying_personal
                    language:
                      code: en
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: Firstname
                          - type: text
                            text: Secondname
              Send a template message with an image:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying_image
                    language:
                      code: en
                    components:
                      type: header
                      parameters:
                        - type: image
                          image:
                            link: https://www.example.com/image.jpg
              Send a template message with a document:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying_document
                    language:
                      code: en
                    components:
                      type: header
                      parameters:
                        - type: document
                          document:
                            link: https://www.example.com/file.zip
                            filename: file.zip
              Send a template message with a video:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying_video
                    language:
                      code: en
                    components:
                      type: header
                      parameters:
                        - type: video
                          video:
                            link: https://www.example.com/video.mov
              Send a template message with payload buttons:
                value:
                  contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  template:
                    name: thanks_for_buying_image
                    language:
                      code: en
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: some text
                      - type: button
                        sub_type: quick_reply
                        index: 0
                        parameters:
                          - type: payload
                            payload:
                              to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Message'
                type: object
      operationId: sendTemplateToContact
      x-ai-role: whatsapp_messaging_specialist
      x-ai-description: >-
        Delivers a pre-approved WhatsApp Business template message to a specific
        contact. Template messages are the only way to initiate outbound
        conversations in WhatsApp (outside the 24-hour service window) — they
        must be pre-approved by Meta and support structured content: variable
        substitution, image/video/document headers, and quick-reply or URL
        buttons. This endpoint is the primary gateway for transactional and
        re-engagement messaging at scale.
      x-ai-reasoning-instructions:
        - >-
          Before sending, confirm the template name and language code are
          correct — an unknown template or mismatched locale will cause an
          immediate failure.
        - >-
          Retrieve the contact_id via a contact search (by tag or variable) if
          the caller only knows an email, phone, or tag.
        - >-
          If the template includes body variables, ensure the `components` array
          contains a `body` entry with `parameters` in the exact order the
          placeholders appear in the template.
        - >-
          For header components, determine the media type first (image / video /
          document) and supply only the matching key — do not mix image and
          video fields in the same parameter object.
        - >-
          When using quick_reply buttons, include `sub_type: quick_reply` and a
          numeric `index` (0–2); omit `sub_type` and `index` for non-button
          components.
        - >-
          All media URLs must use HTTPS (SSL-secured). Validate the URL scheme
          before constructing the request.
        - >-
          If the user provides no components, send an empty array — never omit
          the field when the schema expects it.
      x-ai-responding-instructions:
        - >-
          Confirm delivery by surfacing the `success: true` flag and the
          returned Message ID from the `data` object.
        - >-
          If the call fails, distinguish between a bad template name, a wrong
          language code, a missing required component, and a contact-not-found
          error — each has a different remediation path.
        - >-
          After a successful send, suggest monitoring the message status or
          setting up a webhook to track delivery and read receipts.
        - >-
          When the user sends a template for the first time, remind them that
          WhatsApp limits unsolicited outbound messages and that the 24-hour
          conversation window resets upon contact reply.
      x-ai-suggestions:
        - >-
          Use `getContacts` or a tag-based contact search to resolve
          `contact_id` before calling this endpoint.
        - >-
          Copy the exact `template` object code from the Templates tab in your
          SendPulse bot dashboard to avoid name or language mismatches.
        - >-
          For personalized messages, pass body variable values in the same
          left-to-right order as the `{{1}}`, `{{2}}` placeholders in the
          approved template.
        - >-
          After sending, call the message status endpoint or configure a
          delivery webhook to confirm the contact received the message.
      x-ai-capabilities:
        confirmation:
          type: recommended
          reason: >-
            Sends a real message to a real contact via WhatsApp; accidental
            sends cannot be recalled.
        security_info:
          data_handling:
            - ExternalMessageDelivery
            - PersonalDataTransmission
          notes: >-
            contact_id references PII; media URLs are transmitted to WhatsApp
            infrastructure. Ensure HTTPS-only links and validate contact consent
            before sending.
  /contacts/sendTemplateByPhone:
    post:
      summary: Send a template message to a contact by phone number
      description: >-
        Sends a pre-approved template message to a new or existing contact with
        the specified phone number. You can send a template with variables,
        buttons, image, or document headers. To view an example of the request
        body, select a message template from the drop-down list
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                bot_id:
                  type: string
                  description: >-
                    Bot ID to whose audience you are sending a message. 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.
                phone:
                  type: string
                  description: Contact's phone number in international format.
                template:
                  type: object
                  description: >-
                    Content of the template. To get a template code in your
                    account, go to the "Templates" tab of your bot and, opposite
                    the desired template, click "Copy code." In the opened
                    window, copy the value of the "template" parameter.
                  properties:
                    name:
                      type: string
                      example: event_started
                      description: Template name
                    language:
                      type: object
                      description: Template language
                      properties:
                        code:
                          type: string
                          example: en
                          description: Can have the values en, ru ..
                      required:
                        - code
                    components:
                      type: array
                      description: >-
                        The set of additional parameters differs depending on
                        the included template components and can include
                        variables, an image, or a file.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: >-
                              Accepted values: header / body / footer depending
                              on where you want to insert the component
                          parameters:
                            type: array
                            description: >-
                              Сustom template variables. Specify the type, name
                              and value of the variable
                            items:
                              type: object
                              sub_type:
                                type: string
                                description: >-
                                  Accepted values: url / quick_reply / catalog.
                                  Required when type=button. Not used for the
                                  other types. Type of button to create
                              index:
                                type: int
                                description: >-
                                  Required when type=button. Not used for the
                                  other types. Position index of the button. You
                                  can have up to 3 buttons using index values of
                                  0 to 2.
                              properties:
                                type:
                                  type: string
                                  description: Variable type
                                image:
                                  type: object
                                  description: >-
                                    The image you want to send. Includes the URL
                                    to the image and caption
                                  properties:
                                    link:
                                      type: string
                                      description: >-
                                        Full URL of the file you want to send,
                                        including the "https" protocol part. You
                                        can only send links to SSL-secured sites
                                video:
                                  type: object
                                  description: >-
                                    The video you want to send. Includes the URL
                                    to the video file.
                                  properties:
                                    link:
                                      type: string
                                      description: >-
                                        Full URL of the file you want to send,
                                        including the "https" protocol part. You
                                        can only send links to SSL-secured sites
                                payload:
                                  type: object
                                  description: >-
                                    Required for quick_reply buttons.
                                    Developer-defined payload that is returned
                                    when the button is clicked in addition to
                                    the display text on the button.
                                  properties:
                                    to_chain_id:
                                      type: string
                  required:
                    - name
                    - language
              required:
                - bot_id
                - phone
                - template
            examples:
              Send a simple template message:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying
                    language:
                      code: en
                    components: []
              Send a template message with variables:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying_personal
                    language:
                      code: en
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: Firstname
                          - type: text
                            text: Secondname
              Send a template message with an image:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying_image
                    language:
                      code: en
                    components:
                      type: header
                      parameters:
                        - type: image
                          image:
                            link: https://www.example.com/image.jpg
              Send a template message with a document:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying_document
                    language:
                      code: en
                    components:
                      - type: header
                        parameters:
                          - type: document
                            document:
                              link: https://www.example.com/file.zip
                              filename: file.zip
              Send a template message with a video:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying_video
                    language:
                      code: en
                    components:
                      - type: header
                        parameters:
                          - type: video
                            video:
                              link: https://www.example.com/video.mp4
              Send a template message with payload buttons:
                value:
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  phone: '380931112233'
                  template:
                    name: thanks_for_buying_image
                    language:
                      code: en
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: some text
                      - type: button
                        sub_type: quick_reply
                        index: 0
                        parameters:
                          - type: payload
                            payload:
                              to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Message'
                type: object
      operationId: sendTemplateByPhone
      x-ai-role: whatsapp_messaging_specialist
      x-ai-description: >-
        Sends a pre-approved WhatsApp Business template message to a contact
        identified by phone number. Template messages are the only way to
        initiate or re-engage a conversation outside the 24-hour customer
        service window — they require prior Meta approval and must match exactly
        the registered template structure (name, language, component types).
        This endpoint is the primary channel for transactional notifications,
        order updates, and re-engagement flows.
      x-ai-reasoning-instructions:
        - >-
          Before calling, verify that the template name and language code exist
          and are approved in the WhatsApp Business account — using an
          unapproved or mismatched template will result in an error.
        - >-
          Ensure the phone number is in E.164 international format (e.g.,
          '380931112233') without '+' prefix — leading zeros or local formats
          will fail silently or return errors.
        - >-
          Match the number and types of `components` parameters exactly to the
          template definition; extra or missing variables will cause the request
          to be rejected by Meta.
        - >-
          For templates with a `header` component of type image/video/document,
          the `link` must point to a publicly accessible HTTPS URL; private or
          expired links will result in delivery failure.
        - >-
          For button components with `sub_type: quick_reply`, the `index` must
          correspond to the button's position in the template (0-based);
          incorrect indexing causes wrong button payload routing.
        - >-
          If `components` is empty (`[]`), the template is sent as-is with no
          variable substitution — only use this for static templates.
        - >-
          Confirm the `bot_id` belongs to an active WhatsApp bot; sending via an
          inactive or disconnected bot will silently fail.
      x-ai-responding-instructions:
        - >-
          On success, confirm the message was dispatched and mention the
          contact's phone number and template name used.
        - >-
          If the response includes a Message object, surface the message ID for
          tracking purposes.
        - >-
          If the template has buttons with `to_chain_id`, inform the user that
          clicking the button will trigger the linked automation flow.
        - >-
          If an error occurs related to template structure mismatch, guide the
          user to copy the exact template code from the SendPulse Templates tab
          using the 'Copy code' feature.
        - >-
          Suggest verifying delivery status via the contact's message history if
          no webhook confirmation is expected.
      x-ai-suggestions:
        - >-
          Use for post-purchase confirmations, appointment reminders, or
          shipping notifications outside the 24h window.
        - >-
          Combine with contact lookup to verify the phone number exists before
          sending.
        - >-
          For personalized messages, always pre-fetch the template structure to
          ensure variable count matches.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            You are about to send a WhatsApp template message to {phone} using
            template '{template.name}'. Confirm to proceed.
        security_info:
          data_handling:
            - ExternalMessageDelivery
            - PII_PhoneNumber
          notes: >-
            Phone numbers are PII — do not log or expose them in error messages.
            Template messages consume WhatsApp Business API quota.
  /contacts/sendTyping:
    post:
      summary: Send typing indicator
      description: Initiate typing indicator for the specified contact.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: Payload containing the contact identifier.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_id:
                  type: string
                  description: >-
                    The unique identifier of the contact to whom the typing
                    indicator will be sent.
              required:
                - contact_id
            example:
              contact_id: string
      responses:
        '200':
          description: Indicates whether the typing indicator was successfully sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: boolean
      operationId: sendContactTyping
      x-ai-role: conversational_engagement_specialist
      x-ai-description: >-
        Simulates a typing indicator to a specific contact in a chatbot or
        messaging channel, creating the illusion of a live, human-like
        interaction. This is a UX mechanism — it buys time between messages,
        sets user expectations for an incoming reply, and increases perceived
        responsiveness. It is especially effective before sending a long or
        important message.
      x-ai-reasoning-instructions:
        - >-
          Use this endpoint immediately before sending a substantive message to
          make the conversation feel more natural and human.
        - >-
          Do not trigger typing indicators repeatedly or for extended periods
          without following up with an actual message — this degrades user
          trust.
        - >-
          Ensure the contact_id is valid and the contact is reachable in the
          current channel before sending.
        - >-
          Consider channel context: typing indicators are most impactful in
          real-time channels (e.g., Telegram, Facebook Messenger, WhatsApp).
      x-ai-responding-instructions:
        - Confirm that the typing indicator was successfully dispatched.
        - >-
          If success is false, suggest verifying the contact_id and checking
          channel availability.
        - >-
          Remind the user to follow up promptly with an actual message after
          triggering the indicator.
      x-ai-suggestions:
        - Trigger this before sending a welcome message to new contacts.
        - Use in automation flows to add a human-like pause before a bot reply.
        - Chain with sendMessage to create a natural conversation rhythm.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - TransientSignal
  /contacts/setVariable:
    post:
      summary: Assign a variable to contact
      description: Adds or updates the value of a variable for the selected contact.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: Choose one of available request body
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contact_id
                - variables
              properties:
                contact_id:
                  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.
                variables:
                  type: array
                  description: api.paths.contacts.setVariable.parameters.variables
                  items:
                    oneOf:
                      - type: object
                        required:
                          - variable_name
                          - variable_value
                        properties:
                          variable_name:
                            type: string
                            description: Name of the variable
                          variable_value:
                            description: The value that is set for the variable
                            anyOf:
                              - type: string
                              - type: number
                              - type: boolean
                      - type: object
                        required:
                          - variable_id
                          - variable_value
                        properties:
                          variable_id:
                            type: string
                            description: >-
                              The ID of the created variable can be obtained via
                              other methods
                          variable_value:
                            description: The value that is set for the variable
                            anyOf:
                              - type: string
                              - type: number
                              - type: boolean
            examples:
              Set by variable name:
                value:
                  contact_id: string
                  variables:
                    - variable_name: string
                      variable_value: string
                    - variable_name: string
                      variable_value: string
              Set by variable ID:
                value:
                  contact_id: string
                  variables:
                    - variable_id: string
                      variable_value: string
                    - variable_id: string
                      variable_value: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: setContactVariable
      x-ai-role: chatbot_crm_specialist
      x-ai-description: >-
        Sets or overwrites named variables on a specific chatbot contact,
        forming the persistent data layer that drives personalization and
        conditional bot logic. Variables defined here become available in
        message templates ({{variable_name}}) and flow conditions. This is the
        primary mechanism for syncing external CRM data (e.g., subscription
        tier, order status) into the SendPulse contact profile.
      x-ai-reasoning-instructions:
        - >-
          Resolve `contact_id` first — it is not a phone or email, but an
          internal SendPulse ID. Use contact search endpoints if only an email
          or phone is known.
        - >-
          Prefer `variable_id` over `variable_name` when the variable ID is
          available to avoid silent mismatches due to name typos or renames.
        - >-
          Batch all variable updates for a single contact into one request
          rather than sending multiple sequential calls.
        - >-
          Validate `variable_value` type against the variable's schema — sending
          a string where a number is expected may pass the API but break flow
          conditions silently.
        - >-
          If setting a date-type variable, confirm the expected format (ISO 8601
          is typical) before writing.
      x-ai-responding-instructions:
        - >-
          Confirm which variables were updated and on which contact (include
          `contact_id` in the summary).
        - >-
          If the operation succeeds, suggest verifying the update via a contact
          details endpoint or triggering a flow that depends on the variable.
        - >-
          If `contact_id` is unknown, guide the user to find it via contact
          search by tag or variable, or by opening the chat window in the
          SendPulse UI and reading the URL.
      x-ai-suggestions:
        - >-
          Use this after a purchase event to set `last_order_amount` and
          `subscription_tier` in one call.
        - >-
          Pair with a flow trigger to re-enter the contact into a personalized
          drip sequence after the variable is updated.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ContactDataWrite
            - ResourceStateUpdate
  /contacts/deleteVariable:
    post:
      summary: Delete a variable the selected contact
      description: Delete the value of a variable for the selected contact.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: Choose one of available request body
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                variable_id:
                  type: string
                  description: >-
                    The ID of the created variable can be obtained via other
                    methods
                variable_name:
                  type: string
                  description: Name of the variable
              required:
                '0': contact_id
                oneOf:
                  - variable_id
                  - variable_name
            examples:
              Delete by variable ID:
                value:
                  contact_id: string
                  variable_id: string
              Delete by variable name:
                value:
                  contact_id: string
                  variable_name: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: deleteContactVariable
      x-ai-role: crm_data_steward
      x-ai-description: >-
        Removes the stored value of a specific variable from a contact's
        profile. Use this to clear outdated or incorrect personalization data
        without deleting the contact itself. This is a targeted data correction
        operation — the variable definition remains intact in the system; only
        the contact-level value is erased.
      x-ai-reasoning-instructions:
        - >-
          Prefer identifying the variable by `variable_id` when available — it
          is unambiguous; `variable_name` may match incorrectly if naming is
          inconsistent across the account.
        - >-
          Confirm the `contact_id` is valid before proceeding — an incorrect ID
          will silently fail or affect the wrong contact.
        - >-
          Warn the user if they are about to delete a variable used in active
          automation flows or personalized campaigns, as this may cause
          rendering errors.
        - >-
          Consider whether the intent is to clear the value or to fully remove
          the variable definition — this endpoint only clears the value for one
          contact.
      x-ai-responding-instructions:
        - Confirm which variable was deleted and for which contact.
        - >-
          If the operation succeeds, suggest verifying the contact profile to
          ensure the value is cleared.
        - >-
          If the user seems to want to delete the variable itself (not just its
          value for one contact), clarify that this endpoint only removes the
          value for the specified contact.
      x-ai-suggestions:
        - Use `variable_id` over `variable_name` for precision.
        - >-
          After deletion, call the contact lookup endpoint to verify the
          variable value is cleared.
        - >-
          To reset a variable value rather than delete it, consider updating it
          with an empty string instead.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will permanently remove the variable value for this contact.
            Proceed?
        security_info:
          data_handling:
            - ResourceStateUpdate
            - DataDeletion
  /contacts/setTag:
    post:
      summary: Assign a tag to contact
      description: Assigns tags to the selected contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                tags:
                  type: array
                  description: List of tags to assign to the contact
                  items:
                    type: string
              required:
                - contact_id
                - tags
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: setContactTag
      x-ai-role: crm_contact_management_specialist
      x-ai-description: >-
        Assigns one or more classification tags to a specific contact, enabling
        segmentation, filtering, and targeted automation triggers. Tags in
        SendPulse are flat string labels — unlike variables, they carry no
        value, only membership. This endpoint is the primary mechanism for
        behavioral segmentation after user actions (e.g., purchase, webinar
        attendance, support escalation).
      x-ai-reasoning-instructions:
        - >-
          Obtain the contact_id first — use contact search by tag, variable, or
          retrieve it from the chat window URL in the account.
        - >-
          Ensure tags are meaningful and follow a consistent naming convention
          (e.g., snake_case or PascalCase) to avoid duplicates like 'vip',
          'VIP', 'Vip'.
        - >-
          Multiple tags can be assigned in a single call — batch them if the
          user wants to label a contact with several categories at once.
        - >-
          Tags are additive — this call does not replace existing tags, only
          appends new ones.
        - >-
          Verify that the contact exists before tagging to avoid silent
          failures.
      x-ai-responding-instructions:
        - Confirm which tags were assigned and to which contact_id.
        - >-
          If the user is building a segmentation flow, suggest following up with
          a trigger or automation that uses these tags.
        - >-
          If the operation fails, clarify whether the contact_id was invalid or
          the tags array was malformed.
      x-ai-suggestions:
        - '[''vip'', ''high_priority'']'
        - '[''churned'']'
        - '[''webinar_attendee_march_2025'']'
        - '[''lead'', ''trial_user'']'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/deleteTag:
    post:
      summary: Remove a tag from a contact
      description: Removes the tag for the selected contact.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                tag:
                  type: string
                  description: Tag, you want to remove
              required:
                - contact_id
                - tag
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: deleteContactTag
      x-ai-role: crm_contact_management_specialist
      x-ai-description: >-
        Removes a specific tag from a contact record, effectively excluding the
        contact from any tag-based segmentation or automated flows that rely on
        that tag. Tags in SendPulse serve as lightweight behavioral or status
        labels — removing one can alter which campaigns or chatbot sequences the
        contact qualifies for.
      x-ai-reasoning-instructions:
        - >-
          Confirm the contact_id is valid before attempting removal — use a
          contact search if the ID is uncertain.
        - >-
          Check whether the tag being removed is used in active automation flows
          or audience segments, as removal may silently exclude the contact.
        - >-
          Tags are case-sensitive — verify the exact tag string matches what was
          assigned to the contact.
        - >-
          If the goal is bulk tag removal across many contacts, note this
          endpoint operates on a single contact at a time and must be called
          iteratively.
      x-ai-responding-instructions:
        - >-
          Confirm the tag was successfully removed and mention which contact was
          affected.
        - >-
          If the contact is part of automation that depends on this tag, warn
          the user about potential flow disruption.
        - >-
          Suggest verifying the contact's remaining tags using a contact fetch
          if the user needs to audit the tag state.
      x-ai-suggestions:
        - >-
          Use contact search by tag to retrieve valid contact_id values before
          calling this endpoint.
        - >-
          After removal, fetch the contact record to confirm the tag list
          reflects the change.
        - To add a tag instead, use the corresponding addTag endpoint.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will permanently remove the tag from the contact and may affect
            segmentation or automation flows.
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/disable:
    post:
      summary: Disable contact
      description: >-
        Disables a contact in your audience list. Campaigns and autoflows will
        not be sent to this contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: disableContact
      x-ai-role: audience_management_specialist
      x-ai-description: >-
        Suspends a contact from receiving any outbound communication — campaigns
        and autoflows — without permanently removing them from the audience.
        This is a reversible suppression mechanism useful for compliance, user
        requests (e.g., temporary opt-out), or lifecycle management when the
        contact should be preserved but silenced.
      x-ai-reasoning-instructions:
        - >-
          Confirm the contact_id is valid by searching the contact beforehand if
          uncertain — disabling a wrong contact silently suppresses a live
          audience member.
        - >-
          Distinguish this action from deletion: the contact record is retained
          and can be re-enabled later.
        - >-
          If the user wants to suppress a contact due to a bounce or complaint,
          consider whether a full unsubscribe is more appropriate than a
          disable.
        - >-
          Verify whether the contact is already disabled before calling —
          repeated calls are safe but unnecessary.
      x-ai-responding-instructions:
        - >-
          Confirm that the contact has been successfully disabled and will no
          longer receive campaigns or autoflow messages.
        - >-
          Remind the user that this action is reversible and the contact can be
          re-enabled at any time.
        - >-
          If the user disabled the contact due to a support request or
          compliance reason, suggest documenting the reason externally for audit
          purposes.
      x-ai-suggestions:
        - >-
          Use contact search by tag or variable to retrieve the contact_id
          before calling this endpoint.
        - To re-enable the contact later, use the corresponding enable endpoint.
        - For bulk suppression, consider iterating over a filtered contact list.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will prevent the contact from receiving any future campaigns or
            autoflows. Proceed?
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/enable:
    post:
      summary: Enable contact
      description: >-
        Enables a contact in the audience list and contact start receiving
        campaings and autoflows
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: enableContact
      x-ai-role: audience_lifecycle_manager
      x-ai-description: >-
        Reactivates a previously disabled contact, restoring their eligibility
        to receive campaigns and autoflow sequences. This is a reversible state
        change that affects delivery scope — use it to re-engage contacts who
        were opted out programmatically or suppressed due to inactivity, without
        permanently altering their data.
      x-ai-reasoning-instructions:
        - >-
          Before enabling, verify the contact exists and is currently in a
          disabled state using a contact lookup to avoid unnecessary API calls.
        - >-
          Consider whether the contact was disabled due to a hard bounce, spam
          complaint, or unsubscribe — re-enabling such contacts may harm
          deliverability reputation.
        - >-
          If batch re-activation is needed, ensure this endpoint is called per
          contact rather than expecting bulk support.
      x-ai-responding-instructions:
        - >-
          Confirm the contact has been successfully re-enabled and will now
          receive future campaigns and autoflows.
        - >-
          Suggest verifying the contact's current tag or variable state to
          ensure they fall into the correct audience segments.
        - >-
          If the operation fails, clarify whether the contact_id is invalid or
          the contact is in an unrecoverable suppression state.
      x-ai-suggestions:
        - >-
          Use `searchContactsByTag` or `searchContactsByVariable` to obtain the
          contact_id before calling this endpoint.
        - Follow up with `getContactById` to confirm the updated contact status.
        - >-
          If re-enabling multiple contacts, iterate per contact_id and handle
          errors individually.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            Re-enabling a contact will make them eligible for all active
            campaigns and autoflows. Confirm the contact's suppression reason
            before proceeding.
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/delete:
    post:
      summary: Delete contact
      description: >-
        Removes a contact from the audience and subscribers list. The contact
        can be added back only by subscribing to the bot.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: deleteContact
      x-ai-role: chatbot_audience_manager
      x-ai-description: >-
        Permanently removes a contact from the bot's audience and all associated
        subscriber lists. This is a destructive, irreversible action in the
        sense that the contact can only be re-added if they voluntarily
        re-subscribe to the bot. Use with caution when handling GDPR deletion
        requests or cleaning up invalid contacts.
      x-ai-reasoning-instructions:
        - >-
          Before deleting, confirm the contact_id is correct — use contact
          search by tag or variable to verify identity.
        - >-
          Warn the user that this action removes the contact from all subscriber
          lists associated with the bot, not just a single list.
        - >-
          Check whether the contact has active subscriptions or pending
          campaigns that may be affected by removal.
        - >-
          If the intent is a temporary opt-out rather than a full delete,
          suggest using an unsubscribe flow instead.
      x-ai-responding-instructions:
        - >-
          Confirm successful deletion by referencing the contact_id that was
          removed.
        - >-
          Remind the user that the contact can only return by re-subscribing to
          the bot.
        - >-
          If the operation is part of a compliance (GDPR/CCPA) request, note
          that the contact's data has been removed from the audience.
        - >-
          If the contact_id is not found, suggest verifying it via the contact
          search endpoints.
      x-ai-suggestions:
        - >-
          Retrieve contact_id first using contact search by tag or variable
          before calling this endpoint.
        - >-
          For bulk removals, iterate over a list of contact_ids retrieved from a
          tag-based query.
        - >-
          Consider exporting contact data before deletion if audit trail is
          required.
      x-ai-capabilities:
        confirmation:
          type: Required
          message: >-
            This will permanently remove the contact from the bot audience. They
            can only rejoin by re-subscribing. Confirm deletion?
        security_info:
          data_handling:
            - IrreversibleDelete
            - PII_Removal
  /contacts/getPauseAutomation:
    get:
      summary: Get remaining time for automation pause
      description: 'Returns the time remaining until autoflows are stopped for this contact '
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      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.
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: getContactPauseAutomation
      x-ai-role: chatbot_automation_specialist
      x-ai-description: >-
        Returns the remaining pause duration for autoflows on a specific
        contact. Automation pauses are temporary holds that prevent a contact
        from being triggered by active flows — useful when a human agent is
        handling the conversation or a cooldown period is needed. This endpoint
        allows you to check whether a pause is still active before deciding to
        resume automation or take other actions.
      x-ai-reasoning-instructions:
        - >-
          Retrieve the contact_id first if not already known — use contact
          search by tag, variable, or extract from the chat window URL.
        - >-
          A response with zero or null remaining time means the pause has
          expired and autoflows may resume automatically.
        - >-
          Use this check before sending manual messages to avoid conflicts with
          active automation sequences.
      x-ai-responding-instructions:
        - >-
          Communicate the remaining time in a human-readable format (e.g., '2
          hours 15 minutes remaining').
        - >-
          If the pause has expired, inform the user that automation is likely
          active again.
        - >-
          Suggest resuming or extending the pause depending on the context of
          the conversation.
      x-ai-suggestions:
        - >-
          Check pause status before manually engaging a contact to avoid
          automation conflicts.
        - Combine with `pauseContactAutomation` to extend the pause if needed.
        - Use after a human agent finishes a session to verify pause expiry.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/setPauseAutomation:
    post:
      summary: Pause autoflows for a contact
      description: Pauses autoflows for the specified contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                minutes:
                  type: integer
                  example: 60
                  description: Minutes
              required:
                - contact_id
                - minutes
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: setPauseAutomation
      x-ai-role: marketing_automation_specialist
      x-ai-description: >-
        Temporarily suspends all active autoflows for a specific contact for a
        defined period. This is a precision control mechanism used when a
        contact should not receive automated communications — for example,
        during a sales call, a support escalation, or a manual outreach
        sequence. The pause is time-bound and automatically resumes after the
        specified number of minutes, making it safe to use without remembering
        to re-activate the automation later.
      x-ai-reasoning-instructions:
        - >-
          Verify that the contact_id is valid before calling — use contact
          search by tag or variable if only an email or name is known.
        - >-
          Choose the `minutes` value carefully: too short (e.g., 5 min) may not
          cover the intended interaction window; too long may cause the contact
          to miss scheduled follow-ups.
        - >-
          Consider whether pausing automation is the right action, or if the
          autoflow should be stopped entirely — pausing is temporary and
          reversible.
        - >-
          If the user provides a duration in hours or days, convert to minutes
          before calling (1 hour = 60 min, 1 day = 1440 min).
      x-ai-responding-instructions:
        - >-
          Confirm the pause was applied and mention the contact_id and duration
          in minutes.
        - >-
          If the user provided duration in non-minute units, echo back the
          converted value for clarity.
        - >-
          Suggest setting a reminder or follow-up task for when the automation
          resumes, if the pause is long.
      x-ai-suggestions:
        - Use 60 minutes for a short manual outreach window.
        - Use 1440 minutes (24h) to pause during a support escalation day.
        - Use 10080 minutes (7 days) for a full manual nurturing sequence.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will pause all autoflows for the contact for {{minutes}}
            minutes. Confirm?
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/deletePauseAutomation:
    post:
      summary: Resume autoflows for a contact
      description: Resumes autoflows for the specified contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: deletePauseAutomation
      x-ai-role: marketing_automation_specialist
      x-ai-description: >-
        Removes an active automation pause for a specific contact, immediately
        re-enrolling them into all applicable autoflow sequences. This is
        typically used after a temporary hold — for example, when a support
        issue is resolved or a manual review is complete — to restore normal
        lifecycle automation without manual re-entry.
      x-ai-reasoning-instructions:
        - >-
          Before resuming, confirm the contact actually has an active pause;
          resuming a non-paused contact is a no-op but may indicate a workflow
          logic error.
        - >-
          Verify the contact_id is valid and belongs to the expected account to
          avoid unintended automation triggers for wrong contacts.
        - >-
          Consider whether any autoflows have elapsed or expired during the
          pause period — resumed contacts enter active flows at the current
          state, not from the beginning.
      x-ai-responding-instructions:
        - >-
          Confirm that the pause has been removed and autoflows will resume for
          the contact.
        - >-
          Suggest verifying the contact's current autoflow status using a
          contact lookup if the user needs confirmation.
        - >-
          If the operation fails, check whether the contact_id is correct or
          whether the contact was never paused.
      x-ai-suggestions:
        - >-
          Use after closing a support ticket that triggered a pause to restore
          normal nurture sequences.
        - >-
          Pair with `pauseContactAutomation` to build conditional pause/resume
          logic in orchestration workflows.
        - >-
          After resuming, use a contact detail endpoint to verify active flow
          enrollment.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will immediately re-enroll the contact into all active
            autoflows. Confirm before proceeding if the pause was intentional.
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/notes:
    get:
      summary: Get a list of contact's operator notes
      description: Returns a list of existing operator notes by contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      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: 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.
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              properties:
                success:
                  type: boolean
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
              type: object
      operationId: getContactNotes
      x-ai-role: customer_support_specialist
      x-ai-description: >-
        Retrieves the full history of operator notes attached to a specific
        contact in a bot's conversation context. Notes are internal annotations
        left by human agents — they capture intent, escalation history, or
        personal context that is not visible to the contact. This endpoint is
        the primary source of institutional knowledge about a contact's support
        journey.
      x-ai-reasoning-instructions:
        - >-
          Ensure both `bot_id` and `contact_id` are provided — neither has a
          default and both are mandatory.
        - >-
          If the contact was recently created, notes list may be empty — treat
          an empty array as a valid state, not an error.
        - >-
          Use `bot_id` from the bots list endpoint and `contact_id` from a
          contact search to avoid hardcoding IDs.
        - >-
          Consider paginating or filtering results on the client side if the
          contact has a long support history.
      x-ai-responding-instructions:
        - >-
          Present notes in chronological order if the response contains
          timestamps.
        - >-
          If the notes array is empty, inform the user that no operator notes
          have been added for this contact yet.
        - >-
          Highlight the most recent note as it likely contains the most
          actionable context.
        - >-
          Suggest creating a new note via the appropriate endpoint if no
          relevant note was found.
      x-ai-suggestions:
        - >-
          Use after a support handoff to review prior agent context before
          responding.
        - >-
          Combine with contact variable data to build a full customer profile
          before escalation.
        - >-
          Check notes before closing a ticket to ensure all follow-up actions
          have been recorded.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /contacts/createNote:
    post:
      summary: Send operator note
      description: Sends operator note about contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                bot_id:
                  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.
                text:
                  type: string
                  description: Text of note
              required:
                - contact_id
                - bot_id
                - text
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      operationId: createContactNote
      x-ai-role: customer_support_specialist
      x-ai-description: >-
        Adds an internal operator note to a contact's profile within a bot
        conversation. Notes are not visible to the contact — they serve as
        internal annotations for support teams to document context, issues, or
        follow-up actions. This is a core CRM-like capability for managing
        contact history across chatbot channels.
      x-ai-reasoning-instructions:
        - >-
          Ensure contact_id and bot_id belong to the same channel context —
          mixing IDs from different bots will result in an error.
        - >-
          Notes are internal only; confirm the user understands the text will
          not be sent to the contact.
        - >-
          If the user provides a vague note text, suggest structuring it with
          context (e.g., reason, date, action required).
        - >-
          contact_id and bot_id can be retrieved via contact search or from the
          account URL in an open chat window.
      x-ai-responding-instructions:
        - Confirm the note was successfully attached to the contact.
        - >-
          Remind the user that the note is visible only to operators, not the
          contact.
        - >-
          Suggest reviewing other notes or contact details as a follow-up if
          relevant.
      x-ai-suggestions:
        - Escalate to billing team — payment issue reported
        - VIP customer — handle with priority
        - Waiting for user confirmation before closing ticket
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/updateNote:
    post:
      summary: Update operator note
      description: Updates existing operator notes about contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                bot_id:
                  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.
                text:
                  type: string
                  description: Text of note
                note_id:
                  type: string
                  description: Note ID.
              required:
                - contact_id
                - bot_id
                - text
                - note_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      operationId: updateContactNote
      x-ai-role: crm_support_specialist
      x-ai-description: >-
        Updates an existing operator note attached to a specific contact in a
        bot conversation. Notes are internal annotations visible only to
        operators — they capture context about the contact's history,
        preferences, or pending actions, enabling better continuity across
        support sessions without exposing the information to the end user.
      x-ai-reasoning-instructions:
        - >-
          Ensure you have the correct `note_id` before updating — use the
          contact's notes retrieval method if needed to confirm the target note
          exists.
        - >-
          Verify that `contact_id` and `bot_id` belong to the same conversation
          context; mismatched IDs will cause silent failures or wrong-contact
          updates.
        - >-
          Keep note text concise and action-oriented (e.g., 'Prefers English
          support', 'Awaiting refund confirmation #4421') to maximize utility
          for future operators.
        - >-
          Do not store sensitive personal data (passwords, payment details) in
          notes — treat them as internal CRM annotations only.
      x-ai-responding-instructions:
        - >-
          Confirm that the note was successfully updated and mention the
          `note_id` that was modified.
        - >-
          If the update fails due to a missing or invalid `note_id`, suggest
          retrieving the list of existing notes for this contact first.
        - >-
          Suggest reviewing the updated note in the contact's chat window as a
          quick verification step.
      x-ai-suggestions:
        - Prefers callback over chat — do not send automated follow-ups
        - VIP customer — escalate immediately if issue unresolved after 1 reply
        - Awaiting manager approval — follow up on 2026-04-01
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/deleteNote:
    post:
      summary: Update operator note
      description: Updates existing operator notes about contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                bot_id:
                  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.
                note_id:
                  type: string
                  description: Note ID.
              required:
                - contact_id
                - bot_id
                - note_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      operationId: deleteContactNote
      x-ai-role: crm_contact_manager
      x-ai-description: >-
        Removes an existing operator note tied to a specific contact in a given
        bot. Notes serve as internal annotations visible only to operators —
        used for tracking context, follow-up reminders, or CRM-style commentary.
        Deleting a note is irreversible and affects all operators who may rely
        on it for context in ongoing conversations.
      x-ai-reasoning-instructions:
        - >-
          Confirm that `note_id` belongs to the contact identified by
          `contact_id` before proceeding — mismatched IDs may silently fail or
          affect unintended records.
        - >-
          Verify `bot_id` matches the bot context of the contact; notes are
          scoped per bot.
        - >-
          Treat this as a destructive operation — prompt the user for
          confirmation if the action was not explicitly requested.
        - >-
          If the goal is to update note content rather than delete it, inform
          the user and suggest the appropriate update endpoint instead.
      x-ai-responding-instructions:
        - >-
          Confirm the note was successfully deleted by referencing the
          `note_id`.
        - Warn the user that this action is permanent and cannot be undone.
        - >-
          If the operation fails, clarify whether the issue is an invalid
          `note_id`, wrong `bot_id`, or missing permissions.
        - Suggest reviewing remaining notes on the contact if relevant.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: This will permanently delete the note. Confirm before proceeding.
        security_info:
          data_handling:
            - ResourceDeletion
            - Irreversible
  /contacts/operators/assign:
    post:
      summary: Assign a responsible for the chat.
      description: >-
        Sets the specified operator as responsible for the chat. You can find
        the operator's ID in the https://login.sendpulse.com/settings/#users
        section.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                operator_id:
                  type: integer
                  description: The ID of the operator to assign
              required:
                - contact_id
                - operator_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type:
                      - boolean
                      - 'null'
      operationId: assignContactOperator
      x-ai-role: customer_support_operations_manager
      x-ai-description: >-
        Programmatically assigns a human operator as responsible for a specific
        contact's chat. This is a key action in hybrid bot-human support
        workflows — typically triggered when a conversation requires human
        escalation or when contacts are routed by segment, language, or topic.
        Correct assignment ensures SLA tracking and operator workload balance.
      x-ai-reasoning-instructions:
        - >-
          Verify that the contact_id exists before attempting assignment — use a
          contact lookup endpoint if uncertain.
        - >-
          Verify that the operator_id is active and has access to the chat
          inbox; IDs can be found at
          https://login.sendpulse.com/settings/#users.
        - >-
          Consider whether the contact is already assigned to another operator —
          reassignment may override existing responsibility without warning.
        - >-
          If automating bulk assignment, respect per-operator workload limits to
          avoid overloading specific agents.
      x-ai-responding-instructions:
        - >-
          Confirm successful assignment by mentioning both the contact and the
          operator involved.
        - >-
          If `data` is null or false, clarify that the assignment may have
          failed silently and suggest verifying operator_id validity.
        - >-
          Suggest following up with a message or tag to inform the operator
          about the newly assigned contact.
      x-ai-suggestions:
        - >-
          Use `GET /contacts` with tag or variable filters to retrieve the
          correct contact_id before calling this endpoint.
        - >-
          After assignment, consider sending an internal note or trigger a bot
          flow to notify the operator.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/operators/unAssign:
    post:
      summary: Unassign responsible operators for the chat.
      description: Removes any assigned operator for the chat.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: boolean
      operationId: unAssignContactOperators
      x-ai-role: crm_workflow_coordinator
      x-ai-description: >-
        Releases operator ownership of a contact's chat session. In SendPulse
        CRM, each chat can have a responsible operator assigned for
        accountability and routing. Removing this assignment returns the chat to
        an unowned state — useful when reassigning workload, closing a case, or
        resetting routing so automation rules or other operators can pick it up.
      x-ai-reasoning-instructions:
        - >-
          Verify the contact_id is valid before calling — an invalid ID will
          silently fail or return an error with no operator change.
        - >-
          Check whether the contact currently has an assigned operator;
          unassigning an already-unassigned contact is a no-op but may confuse
          the user.
        - >-
          Consider whether the intent is to reassign (use assignOperator
          afterward) or to fully release the chat to queue/automation.
        - >-
          In team workflows, confirm with the user that removing the operator
          won't leave the contact without follow-up coverage.
      x-ai-responding-instructions:
        - Confirm the operator was successfully removed from the contact's chat.
        - >-
          If data: true is returned, state clearly that the chat is now
          unassigned.
        - >-
          Suggest a follow-up action — either assigning a new operator or
          leaving the chat for queue-based routing.
        - >-
          If the operation fails, clarify whether the contact_id was incorrect
          or the contact had no operator assigned.
      x-ai-suggestions:
        - Use before reassigning the chat to a different operator.
        - >-
          Combine with a subsequent assignOperator call for atomic reassignment
          logic.
        - >-
          Useful in automation flows triggered by case resolution or shift
          handoff.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will remove the currently assigned operator from the contact's
            chat. Proceed?
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/setName:
    post:
      summary: Set the contact's name
      description: Updates the display name of the specified contact.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  type: string
                  description: >-
                    The unique identifier of the contact. You can obtain this
                    via a contact search by certain criteria or retrieve it from
                    the address bar of the contact’s chat window in your
                    account.
                name:
                  type: string
                  description: The new name to assign to the contact.
              required:
                - contact_id
                - name
      responses:
        '200':
          description: Operation successful1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: setContactName
      x-ai-role: crm_data_specialist
      x-ai-description: >-
        Updates the human-readable display name of a contact in the CRM. This is
        a cosmetic but operationally significant action — contact names appear
        in chat windows, campaign logs, and agent interfaces. Renaming improves
        personalization accuracy and helps agents distinguish contacts when
        multiple records share similar attributes.
      x-ai-reasoning-instructions:
        - >-
          Obtain the contact_id first — use a contact search endpoint if only a
          name or phone number is known.
        - >-
          Confirm the new name is non-empty and does not contain control
          characters or excessive whitespace before sending.
        - >-
          If the caller provides a full name, consider whether the system
          expects a single 'name' field or separate first/last — this endpoint
          uses a single combined field.
        - >-
          Avoid overwriting an existing meaningful name with a generic
          placeholder unless explicitly instructed by the user.
      x-ai-responding-instructions:
        - >-
          Confirm the rename by echoing both the contact_id and the new name
          that was applied.
        - >-
          If the operation succeeds, suggest verifying the change by opening the
          contact's chat window or fetching the contact record.
        - >-
          If the contact_id is invalid or not found, explain how to retrieve the
          correct ID via contact search.
      x-ai-suggestions:
        - >-
          Use `searchContacts` or equivalent to resolve a contact_id from a
          phone number or email before calling this endpoint.
        - >-
          After renaming, consider updating other contact fields (e.g., tags,
          variables) in a single session for consistency.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/openChat:
    post:
      summary: Open chat for a contact
      description: Increase the chat priority by marking it as open
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Chat opened successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: openContactChat
      x-ai-role: customer_support_specialist
      x-ai-description: >-
        Marks a contact's chat as open, elevating its priority in the support
        queue. In SendPulse, 'open' chats are surfaced to agents as requiring
        attention — this is a triage action, not just a status flag. Use this
        when an automated flow or agent detects a contact needing human
        follow-up, or to re-escalate a previously resolved conversation.
      x-ai-reasoning-instructions:
        - >-
          Verify the contact_id is valid before calling — use a contact search
          by tag or variable if the ID is not directly available.
        - Check whether the chat is already open to avoid redundant calls.
        - >-
          Consider the broader workflow: opening a chat may trigger agent
          notifications or SLA timers depending on account configuration.
        - >-
          If called within an automation, ensure this action is intentional —
          mass-opening chats can overwhelm support queues.
      x-ai-responding-instructions:
        - Confirm that the chat has been successfully marked as open.
        - >-
          Suggest assigning the chat to a specific agent or team as a logical
          next step.
        - >-
          If the contact_id is not found, guide the user on how to retrieve it
          via contact search or from the account UI address bar.
      x-ai-suggestions:
        - >-
          Use `getContactByTag` or `getContactByVariable` to look up contact_id
          if not known.
        - >-
          After opening, consider using an assign-agent endpoint to route the
          chat immediately.
        - Pair with a notification action to alert the support team.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
  /contacts/closeChat:
    post:
      summary: Close chat for a contact
      description: Close the chat and lower the priority.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - contacts
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
              required:
                - contact_id
      responses:
        '200':
          description: Chat closed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: closeContactChat
      x-ai-role: customer_support_manager
      x-ai-description: >-
        Closes the active chat session for a specific contact and reduces its
        queue priority. This is a workflow state-transition endpoint — it
        signals that the conversation is resolved and no longer requires agent
        attention. Lowering priority ensures the contact's thread is
        deprioritized in the support queue, preventing it from surfacing again
        unless a new message arrives. Typically used after issue resolution or
        when a conversation becomes inactive.
      x-ai-reasoning-instructions:
        - >-
          Before closing, confirm the contact_id belongs to an active or open
          chat — closing an already-closed chat may produce an error or be a
          no-op.
        - >-
          Consider whether the conversation was fully resolved before closing;
          closing prematurely may degrade customer experience.
        - >-
          If the intent is bulk-closing, this endpoint must be called
          per-contact — there is no batch variant.
        - >-
          If the contact later sends a message, the chat will typically reopen
          automatically — inform the user of this behavior if relevant.
      x-ai-responding-instructions:
        - >-
          Confirm that the chat was successfully closed and that its priority
          has been lowered.
        - >-
          Remind the user that new inbound messages from this contact will
          reopen the conversation.
        - >-
          If the contact_id was not found or the chat was already closed,
          explain the likely cause clearly.
      x-ai-suggestions:
        - >-
          Use after sending a closing message to the contact to finalize the
          support interaction.
        - >-
          Combine with contact tagging (e.g., 'resolved') to maintain
          conversation history context.
        - Useful in automation flows triggered by inactivity timeouts.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will close the chat and lower its priority. The contact will
            need to send a new message to reopen it.
        security_info:
          data_handling:
            - ResourceStateUpdate
  /flows:
    get:
      summary: Get a list of flows
      description: >-
        Returns a list of created flows for the selected bot and information for
        each: flow id, bot id, status, name, id and name of the trigger that
        launches it, and creation date
      security:
        - oAuth2ClientCredentials: []
      tags:
        - flows
      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
          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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Flow'
                type: object
      operationId: listFlows
      x-ai-role: chatbot_automation_specialist
      x-ai-description: >-
        Retrieves the full inventory of automation flows for a given bot. A flow
        is a trigger-driven conversation scenario — the core building block of
        chatbot logic in SendPulse. Use this endpoint to audit existing
        automation, find flow IDs for linking triggers, or inspect the
        active/inactive state of each scenario before making changes.
      x-ai-reasoning-instructions:
        - >-
          Always require bot_id — without it the request is invalid; confirm the
          user has it before calling.
        - >-
          If the user doesn't know their bot_id, direct them to the 'get list of
          bots' endpoint first.
        - >-
          Use 'size' and 'skip' together for pagination; if the user needs all
          flows, loop until the returned batch is smaller than 'size'.
        - >-
          If the user is looking for a specific flow by name, fetch all pages
          and filter client-side — there is no server-side name filter.
      x-ai-responding-instructions:
        - >-
          Present results as a structured list: flow name, ID, status
          (active/inactive), and trigger name.
        - >-
          Highlight any flows with an inactive status — the user may want to
          re-enable them.
        - >-
          If the list is empty, suggest the user create a flow in the SendPulse
          dashboard first.
        - >-
          Mention the flow ID prominently — it is the key reference for trigger
          assignment and flow management operations.
      x-ai-suggestions:
        - >-
          Use the returned flow IDs with 'get flow by ID' or trigger-assignment
          endpoints.
        - Filter by status client-side to quickly identify disabled automations.
        - Start with size=50 and skip=0, then paginate if 50 items are returned.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /flows/run:
    post:
      summary: Run a flow by its ID
      description: >-
        Launches the selected flow for the selected contact. Additional data can
        be passed to the "external_data" field and used once in the selected
        chain, where variables will be inserted in the "Message" element as a
        JSON path, for example {{$['tracking_number']}}.
      security:
        - oAuth2ClientCredentials: []
      tags:
        - flows
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                flow_id:
                  type: string
                  description: >-
                    Flow ID to be launched. Can be obtained with the method of
                    obtaining the list of flows
                external_data:
                  type: object
                  description: >-
                    Custom variables. You can pass variable values in the
                    request and use them once in the flow you selected. To add
                    variables to the flow, in the Message element, insert the
                    variable names as a JSON path expression
                    {{$['somekey']['nestedkey']}}.
                  example:
                    tracking_number: 1234-0987-5678-9012
              required:
                - contact_id
                - flow_id
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: runFlow
      x-ai-role: marketing_automation_specialist
      x-ai-description: >-
        Triggers a pre-built automation flow for a specific contact. This is the
        execution entry point for chatbot/messaging automation — it bridges
        CRM-level contact data with a configured message sequence. The
        `external_data` payload enables one-time, per-execution variable
        injection, making the same flow reusable across different transactional
        contexts (e.g., order tracking, shipping notifications) without
        modifying the flow itself.
      x-ai-reasoning-instructions:
        - >-
          Resolve `contact_id` before calling this endpoint — use contact search
          by tag or variable if only a phone/email is known.
        - >-
          Resolve `flow_id` via the list-flows endpoint if the caller only knows
          the flow name.
        - >-
          If `external_data` is provided, verify that the flow actually contains
          `{{$[...]}}` variable references — otherwise the data is silently
          ignored.
        - >-
          Check that the contact belongs to the correct channel the flow targets
          (e.g., WhatsApp, Telegram) to avoid silent no-ops.
        - >-
          Do not retry on success — this endpoint triggers a live message send;
          duplicate calls will launch the flow multiple times.
      x-ai-responding-instructions:
        - >-
          Confirm that the flow was launched and mention the contact and flow
          IDs used.
        - >-
          If `external_data` was passed, acknowledge which variables were
          injected.
        - >-
          If the response indicates failure, explain likely causes: invalid
          contact_id, flow not active, or channel mismatch.
        - >-
          Suggest verifying delivery in the SendPulse account chat history if
          the caller needs confirmation of receipt.
      x-ai-suggestions:
        - >-
          Use `getFlows` first to resolve a human-readable flow name to its
          `flow_id`.
        - >-
          Use contact search endpoints to resolve a phone number or email to
          `contact_id`.
        - >-
          Pass order/shipment identifiers in `external_data` for transactional
          notification flows.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This action immediately sends messages to a live contact. Confirm
            the correct contact and flow before proceeding.
        security_info:
          data_handling:
            - ExternalDataInjection
            - LiveMessageDispatch
  /flows/runByTrigger:
    post:
      summary: Run a flow by trigger keywords
      description: Launches a flow with the trigger keyword for the selected contact
      security:
        - oAuth2ClientCredentials: []
      tags:
        - flows
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                contact_id:
                  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.
                trigger_keyword:
                  type: string
                  description: Keyword (command) that launch the flow
                external_data:
                  type: object
                  description: >-
                    Custom variables. You can pass variable values in the
                    request and use them once in the flow you selected. To add
                    variables to the flow, in the Message element, insert the
                    variable names as a JSON path expression
                    {{$['somekey']['nestedkey']}}.
                  example:
                    tracking_number: 1234-0987-5678-9012
              required:
                - contact_id
                - trigger_keyword
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      operationId: runFlowByTrigger
      x-ai-role: chatbot_automation_specialist
      x-ai-description: >-
        Programmatically triggers a chatbot flow for a specific contact by
        injecting a keyword command — the same mechanism used when a user sends
        a trigger word in chat. This is the primary bridge between external
        systems (CRM, e-commerce, webhooks) and SendPulse automation: it allows
        event-driven flow activation (e.g., order shipped → trigger 'tracking'
        flow) without any user action in the chat. The `external_data` field
        enables one-time variable injection, making the flow execution
        context-aware.
      x-ai-reasoning-instructions:
        - >-
          Verify that `contact_id` belongs to the correct channel (chatbot type)
          before triggering — flows are channel-specific.
        - >-
          Confirm that the `trigger_keyword` exactly matches a keyword
          configured in the flow; case sensitivity and spaces may matter.
        - >-
          If `external_data` is provided, validate that the keys match the
          variable names used in the flow's Message elements (JSON path format).
        - >-
          Warn the user that `external_data` variables are single-use — they are
          consumed by the flow execution and not persisted to the contact's
          profile.
        - >-
          Check whether the contact has an active session or has opted in;
          triggering a flow on an unsubscribed contact may fail silently.
      x-ai-responding-instructions:
        - >-
          Confirm the flow was triggered successfully and mention the contact
          and keyword used.
        - >-
          If `external_data` was passed, note that the variables were injected
          for this execution only.
        - >-
          Suggest verifying the result in the SendPulse chatbot statistics or
          flow execution logs.
        - >-
          On failure, help the user diagnose whether the issue is an invalid
          contact ID, unknown keyword, or missing flow configuration.
      x-ai-suggestions:
        - >-
          Use this endpoint in post-purchase webhooks to trigger order
          confirmation or tracking flows.
        - >-
          Combine with contact search endpoints to resolve `contact_id`
          dynamically by tag or variable.
        - >-
          For bulk triggering across a segment, iterate contacts from a list and
          call this endpoint per contact.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: >-
            This will immediately send automated messages to the contact via the
            configured flow.
        security_info:
          data_handling:
            - ExternalDataInjection
            - ContactInteraction
  /triggers:
    get:
      summary: Get a list of triggers
      description: >-
        Returns the list of created triggers for the selected bot with
        information about each of them: trigger ID, bot id, id of the flow that
        starts on it, name, type, set launch time and creation date
      security:
        - oAuth2ClientCredentials: []
      tags:
        - triggers
      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
          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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trigger'
                type: object
      operationId: getTriggers
      x-ai-role: chatbot_automation_specialist
      x-ai-description: >-
        Retrieves the full list of automation triggers configured for a specific
        bot. Triggers are the entry points of chatbot flows — they define what
        event or condition initiates a conversation scenario. Understanding the
        trigger landscape for a bot is essential before modifying flows,
        diagnosing automation issues, or auditing bot behavior.
      x-ai-reasoning-instructions:
        - >-
          Always require bot_id before calling — triggers are bot-scoped and
          have no meaning without it.
        - >-
          If the user wants to find a specific trigger, fetch the full list
          first and filter by name or type client-side unless the API supports
          filtering.
        - >-
          Use `size` and `skip` for bots with many triggers to avoid oversized
          responses.
        - >-
          Cross-reference returned flow IDs with flow management endpoints to
          inspect what each trigger launches.
      x-ai-responding-instructions:
        - >-
          Present triggers grouped by type (e.g., keyword, welcome, default) if
          multiple types are present.
        - >-
          Highlight trigger names and their associated flow IDs so the user can
          quickly identify which flow runs on each trigger.
        - >-
          If the list is empty, suggest creating a trigger or verifying the
          correct bot_id was used.
        - Mention pagination parameters if the result set appears truncated.
      x-ai-suggestions:
        - >-
          Use the returned flow IDs with the flows API to inspect or modify the
          automation logic.
        - >-
          Check trigger `type` values to understand the full automation coverage
          of the bot.
        - >-
          If looking for a specific trigger, filter the returned array by `name`
          or `type`.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /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
      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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bot'
                type: object
      operationId: listBots
      x-ai-role: chatbot_operations_manager
      x-ai-description: >-
        Retrieves a paginated inventory of all bots connected to the account
        across supported messaging channels. Each bot entry reflects its current
        operational status, message throughput (received vs unread), and channel
        metadata — making this the primary endpoint for bot fleet monitoring and
        health checks.
      x-ai-reasoning-instructions:
        - >-
          Use this endpoint first to discover available bot IDs before
          performing operations that require a specific bot_id.
        - >-
          If the user asks about a specific channel (Telegram, WhatsApp, etc.),
          filter the response client-side by channel type after fetching the
          full list.
        - >-
          When paginating, use `skip` as an offset multiplier: skip=0 for page
          1, skip=size for page 2, etc.
        - >-
          A high unread message count relative to received may indicate a bot
          that is connected but not processing — flag this to the user.
        - >-
          Check `status` field to warn user if any bots are inactive before
          recommending them for campaign use.
      x-ai-responding-instructions:
        - >-
          Present the result as a structured summary: total bots found, list of
          bot names/IDs with their channel and status.
        - >-
          Highlight any bots with inactive status or unusually high unread
          counts.
        - >-
          If the list is empty, suggest connecting a bot via the SendPulse
          dashboard.
        - >-
          If paginating, inform the user how many items were returned and
          suggest increasing `size` or adjusting `skip` if more bots are
          expected.
      x-ai-suggestions:
        - >-
          Call this endpoint to resolve a bot name to its ID before sending
          messages or creating flows.
        - >-
          Use size=50 for a full account overview; use size=10 with skip for
          paginated dashboards.
        - >-
          Follow up with GET /bots/{id} to retrieve detailed configuration for a
          specific bot.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /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_analytics_specialist
      x-ai-description: >-
        Returns a high-level health snapshot of a specific bot: how many
        subscribers are active vs total, and the total volume of outgoing
        messages. Use this endpoint to assess bot engagement before launching a
        broadcast or when auditing audience quality. Active subscriber count is
        the operational metric — inactive subscribers inflate totals but do not
        receive messages.
      x-ai-reasoning-instructions:
        - >-
          Resolve the bot_id first — if the user has not provided it, call the
          list-bots endpoint to enumerate available bots.
        - >-
          Compare subscribedActiveCount vs subscribedTotalCount to gauge list
          health; a large gap signals a significant inactive/unsubscribed
          portion.
        - >-
          Use outgoingMessagesTotalCount as a baseline when estimating broadcast
          reach or cost projections.
      x-ai-responding-instructions:
        - >-
          Present the active/total subscriber ratio as a percentage to make
          audience quality immediately clear.
        - >-
          If active count is significantly lower than total, flag potential list
          hygiene issues.
        - >-
          Suggest follow-up actions such as filtering inactive subscribers or
          scheduling a re-engagement campaign.
      x-ai-suggestions:
        - Check this before a broadcast to confirm you have an audience.
        - >-
          Use alongside `getBotFlow` or broadcast endpoints to correlate message
          volume with campaign history.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /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:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chat'
                type: object
      operationId: getChats
      x-ai-role: conversational_marketing_specialist
      x-ai-description: >-
        Retrieves a paginated list of active chat sessions between the bot and
        its subscribers. Each chat entry includes contact profile data and the
        last inbound message — forming a real-time inbox view for the bot. This
        is the primary discovery endpoint before acting on individual
        conversations (e.g., sending replies, tagging contacts, or triggering
        flows).
      x-ai-reasoning-instructions:
        - >-
          Always require bot_id — it scopes all results to a specific bot;
          prompt the user to retrieve it via the 'get bots list' endpoint if
          unknown.
        - >-
          Use 'skip' and 'size' to paginate large contact bases; default page
          size may be small — iterate if the user needs the full list.
        - >-
          If the user wants to find a specific contact, this endpoint returns a
          list — filter client-side or use a dedicated contact-search endpoint
          if available.
        - >-
          The last message in each chat reflects inbound traffic only; do not
          assume it represents the full conversation state.
      x-ai-responding-instructions:
        - >-
          Summarize how many chats were returned and whether pagination was
          applied.
        - >-
          If the list is empty, suggest verifying the bot_id or checking whether
          any subscribers have initiated contact.
        - >-
          Highlight contact identifiers (e.g., subscriber IDs) so the user can
          reference them in follow-up operations like sending messages or
          updating contact data.
        - >-
          Suggest using 'skip' + 'size' parameters to page through results if
          the dataset appears truncated.
      x-ai-suggestions:
        - 'Fetch the first 20 chats: bot_id=<id>&size=20&skip=0'
        - >-
          Use returned subscriber IDs to send targeted messages via the 'send
          message' endpoint.
        - >-
          Cross-reference last message timestamps to identify inactive or
          unresponsive contacts.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /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: search_after
          description: The id of 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: array
                    items:
                      $ref: '#/components/schemas/Message'
                type: object
      operationId: getChatMessages
      x-ai-role: customer_communication_analyst
      x-ai-description: >-
        Retrieves the full conversation history with a specific subscriber
        across all channels. This is the primary endpoint for reconstructing
        dialogue context before crafting a reply, auditing communication
        timelines, or feeding message history into an AI agent for sentiment
        analysis or support escalation decisions.
      x-ai-reasoning-instructions:
        - >-
          Always resolve `contact_id` first — it is mandatory. If only a name or
          email is known, use the contact search endpoint before calling this
          one.
        - >-
          For long conversations, use `size` + `skip` or cursor-based
          `search_after` pagination to avoid incomplete results.
        - >-
          Use `order: desc` when the goal is to read the most recent messages
          first (e.g., last-message previews or real-time support contexts).
        - >-
          Use `order: asc` when reconstructing a conversation thread
          chronologically for analysis or export.
        - >-
          If `search_after` is provided, it takes precedence over `skip` for
          deep pagination — prefer it for large datasets.
      x-ai-responding-instructions:
        - >-
          Present messages in a readable, chronological or reverse-chronological
          format depending on the requested order.
        - >-
          Indicate the total number of messages returned and whether pagination
          is likely needed.
        - >-
          If the result is empty, suggest verifying the `contact_id` or
          confirming the contact has an active conversation.
        - >-
          Highlight the direction of each message (inbound from subscriber vs.
          outbound from agent/bot) if schema allows.
      x-ai-suggestions:
        - >-
          Fetch the last 20 messages with `size=20&order=desc` for a quick
          conversation preview.
        - >-
          Use `search_after` with the last returned message ID to efficiently
          paginate through large histories.
        - >-
          Combine with `getContacts` or contact search to resolve `contact_id`
          by email or phone before calling.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
            - PersonalData
  /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
  /variables:
    get:
      summary: Get a list of variables
      description: >-
        Returns a list of variables for the selected bot with information about
        each: variable ID, bot ID, name, affiliation, type, status, and creation
        date
      security:
        - oAuth2ClientCredentials: []
      tags:
        - variables
      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
          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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Variable'
                type: object
      operationId: getBotVariables
      x-ai-role: chatbot_automation_specialist
      x-ai-description: >-
        Retrieves the full schema of variables defined for a specific bot — each
        variable acts as a dynamic data slot attached to contacts, enabling
        personalized message flows and conditional logic within chatbot
        scenarios. Understanding variable structure is essential before reading
        or writing contact-level data.
      x-ai-reasoning-instructions:
        - >-
          Resolve the bot_id first — if the user hasn't provided it, call the
          list-bots endpoint before proceeding.
        - >-
          Use 'size' and 'skip' for pagination when a bot has many variables;
          default page size may be small.
        - >-
          Distinguish variable types (e.g., string, number, boolean) from the
          response before attempting to write values — type mismatches cause
          silent failures.
        - >-
          If the response is empty, the bot likely has no variables defined yet
          — suggest creating them via the variable management endpoints.
      x-ai-responding-instructions:
        - >-
          Present variables in a structured summary: name, type, and affiliation
          (contact-level vs bot-level).
        - >-
          If the user is looking for a specific variable, highlight it and
          provide its ID for downstream use.
        - >-
          If pagination params were not supplied and the result looks truncated,
          recommend repeating the call with explicit 'size' and 'skip'.
        - >-
          Suggest the next logical step: reading or updating contact variable
          values using the returned variable IDs.
      x-ai-suggestions:
        - >-
          Fetch all variables before building a contact update payload to ensure
          correct variable IDs and types.
        - >-
          Use 'skip' in multiples of 'size' to paginate: skip=0, skip=20,
          skip=40, etc.
        - >-
          Cross-reference variable 'affiliation' to understand scope:
          contact-scoped variables hold per-user state.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /campaigns/send:
    post:
      summary: Send campaign
      description: >-
        Sends a campaign to all of a bot's subscribers that were active within
        the last 24 hours. You can send a campaign with text, an image, or a
        file. To view an example of the request body, select a message type from
        the drop-down list
      security:
        - oAuth2ClientCredentials: []
      tags:
        - campaigns
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                title:
                  type: string
                  description: Campaign title
                bot_id:
                  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.
                send_at:
                  type: string
                  description: >-
                    Specify the date and time in the format Y-m-d H:i if you
                    need to schedule the campaign, if you do not specify this
                    parameter, the campaign will be sent immediately
                  example: Y-m-d H:i
                filter:
                  type: object
                  description: Filter for campaign sending
                  properties:
                    type:
                      type: string
                      description: Filter type (and/or)
                    expressions:
                      type: array
                      description: Filter expressions
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Expression type (and/or)
                          expressions:
                            type: array
                            description: List of expressions
                            items:
                              type: object
                              properties:
                                operator:
                                  type: string
                                  description: >-
                                    Filter operator (e.g., eq, like, gt, lt,
                                    etc.)
                                field:
                                  type: string
                                  description: Field to filter by (e.g., tags)
                                value:
                                  type: string
                                  description: Value to filter by
                messages:
                  type: array
                  description: >-
                    Message to send, specifying the type and content of the
                    campaign
                  items:
                    type: object
                    description: api.paths.contacts.sendText.parameters.message
                    properties:
                      type:
                        type: string
                        enum:
                          - text
                          - image
                          - document
                        description: api.paths.contacts.sendText.parameters.message_type
                        example: text
                      text:
                        type: object
                        properties:
                          body:
                            type: string
                            description: >-
                              The content of the text message. You can add text
                              with emoji of up to 1024 unicode characters.
                        required:
                          - body
                      image:
                        type: object
                        description: api.paths.contacts.sendText.parameters.image
                        properties:
                          link:
                            type: string
                            description: api.paths.contacts.sendText.parameters.image_url
                          caption:
                            type:
                              - string
                              - 'null'
                            description: >-
                              api.paths.contacts.sendText.parameters.image_caption
                        required:
                          - link
                      file:
                        type: object
                        description: api.paths.contacts.sendText.parameters.file
                        properties:
                          link:
                            type: string
                            description: api.paths.contacts.sendText.parameters.file_url
                          caption:
                            type:
                              - string
                              - 'null'
                            description: >-
                              api.paths.contacts.sendText.parameters.file_caption
                        required:
                          - link
                    required:
                      - type
              required:
                - title
                - bot_id
                - messages
            examples:
              Send a campaign with text:
                value:
                  title: string
                  bot_id: string
                  send_at: Y-m-d H:i
                  filter:
                    type: and
                    expressions:
                      - type: and
                        expressions:
                          - operator: eq
                            field: tags
                            value: SOME_TAG_HERE
                  messages:
                    - type: text
                      text:
                        body: string
              Send a campaign with an image:
                value:
                  title: string
                  bot_id: string
                  send_at: Y-m-d H:i
                  messages:
                    - type: image
                      image:
                        link: string
                        caption: string
              Send a campaign with a file:
                value:
                  title: string
                  bot_id: string
                  send_at: Y-m-d H:i
                  messages:
                    - type: document
                      document:
                        link: string
                        caption: string
              Send a campaign with different content types:
                value:
                  title: string
                  bot_id: string
                  send_at: Y-m-d H:i
                  messages:
                    - type: text
                      text:
                        body: string
                    - type: image
                      image:
                        link: string
                        caption: string
                    - type: document
                      document:
                        link: string
                        caption: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Campaign'
                type: object
      operationId: sendCampaign
      x-ai-role: chatbot_campaign_manager
      x-ai-description: >-
        Broadcasts a message campaign to all active subscribers of a specific
        bot who interacted within the last 24 hours. This is the primary
        mass-communication action in the WhatsApp chatbot channel — it initiates
        a one-to-many push that cannot be recalled once sent. Supports immediate
        or scheduled delivery, optional audience filtering by tags or custom
        fields, and multi-type message payloads (text, image, document) within a
        single campaign.
      x-ai-reasoning-instructions:
        - >-
          Verify the bot_id is valid and belongs to the user's account before
          proceeding — use the 'get bots list' method if uncertain.
        - >-
          Confirm the target audience: if no filter is provided, the campaign
          will be sent to ALL active subscribers; always warn the user if the
          scope seems unintentionally broad.
        - >-
          If send_at is specified, validate the datetime format strictly as
          'Y-m-d H:i' (e.g., '2024-12-31 14:00'); incorrect format will cause
          the campaign to fail silently or send immediately.
        - >-
          When multiple message types are included in the messages array, ensure
          each object has the correct required nested field (text.body,
          image.link, file.link) matching its type.
        - >-
          Remind the user that only subscribers active within the last 24 hours
          will receive the campaign — low recent activity may result in a very
          small reach.
        - >-
          If a filter is used, validate that the filter structure is correct:
          top-level 'type' (and/or) with nested expressions before calling.
      x-ai-responding-instructions:
        - >-
          Confirm whether the campaign was scheduled or sent immediately, and
          mention the campaign ID from the response data for tracking.
        - >-
          If a filter was applied, acknowledge the audience scope (e.g., 'sent
          only to subscribers tagged X').
        - >-
          If the response indicates failure, explain the likely cause (invalid
          bot_id, malformed payload, inactive subscribers) and suggest
          corrective action.
        - >-
          Suggest using the campaign retrieval endpoint to monitor delivery
          status after a scheduled campaign is queued.
      x-ai-suggestions:
        - Weekly_Newsletter_Blast
        - Promo_Flash_Sale_24h
        - Onboarding_Reminder_New_Users
      x-ai-capabilities:
        confirmation:
          type: Required
          message: >-
            This action will broadcast a message to all active bot subscribers
            (last 24h). If no filter is set, the entire active audience will be
            reached. Confirm before sending.
        security_info:
          data_handling:
            - MassCommunicationTrigger
            - IrreversibleAction
  /campaigns/sendTemplate:
    post:
      summary: Send a campaign by template
      description: >-
        Sends a template message to all of a bot's subsribers. You can send a
        campaign with text, an image, or a file. To view an example of the
        request body, select a message template from the drop-down list
      security:
        - oAuth2ClientCredentials: []
      tags:
        - campaigns
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              properties:
                title:
                  type: string
                  description: Campaign title
                bot_id:
                  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.
                send_at:
                  type: string
                  description: >-
                    Specify the date and time in the format Y-m-d H:i if you
                    need to schedule the campaign, if you do not specify this
                    parameter, the campaign will be sent immediately
                  example: Y-m-d H:i
                template:
                  type: object
                  description: >-
                    Content of the template. To get a template code in your
                    account, go to the "Templates" tab of your bot and, opposite
                    the desired template, click "Copy code." In the opened
                    window, copy the value of the "template" parameter.
                  properties:
                    name:
                      type: string
                      example: event_started
                      description: Template name
                    language:
                      type: object
                      description: Template language
                      properties:
                        code:
                          type: string
                          example: en
                      required:
                        - code
                    components:
                      type: array
                      description: >-
                        The set of additional parameters differs depending on
                        the included template components and can include
                        variables, an image, or a file.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: >-
                              Accepted values: header / body / footer depending
                              on where you want to insert the component
                          sub_type:
                            type: string
                            description: >-
                              Accepted values: url / quick_reply / catalog.
                              Required when type=button. Not used for the other
                              types. Type of button to create
                          index:
                            type: int
                            description: >-
                              Required when type=button. Not used for the other
                              types. Position index of the button. You can have
                              up to 3 buttons using index values of 0 to 2.
                          parameters:
                            type: array
                            description: >-
                              Сustom template variables. Specify the type, name
                              and value of the variable
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                  description: Variable type
                                image:
                                  type: object
                                  description: >-
                                    The image you want to send. Includes the URL
                                    to the image and caption
                                  properties:
                                    link:
                                      type: string
                                      description: >-
                                        Full URL of the file you want to send,
                                        including the "https" protocol part. You
                                        can only send links to SSL-secured sites
                                    caption:
                                      type: string
                                      description: Caption for the image
                                payload:
                                  type: string
                                  description: >-
                                    Required for quick_reply buttons.
                                    Developer-defined payload that is returned
                                    when the button is clicked in addition to
                                    the display text on the button.
                  required:
                    - name
                    - language
              required:
                - title
                - bot_id
                - template
            examples:
              Send a campaign by template with text:
                value:
                  title: Thanks for buying
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  send_at: 2021-01-21 12:00
                  template:
                    name: thanks_for_buying
                    language:
                      code: en
                    components: []
              Send a campaign by template with an image:
                value:
                  title: Thanks for buying
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  send_at: 2021-01-21 12:00
                  template:
                    name: thanks_for_buying_image
                    language:
                      code: en
                    components:
                      type: header
                      parameters:
                        - type: image
                          image:
                            link: https://www.example.com/image.jpg
              Send a template message with payload buttons:
                value:
                  title: Thanks for buying
                  bot_id: xxxxxxxxxxxxxxxxxxxxxxxx
                  send_at: 2021-01-21 12:00
                  template:
                    name: thanks_for_buying_payload
                    language:
                      code: en
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: some text
                      - type: button
                        sub_type: quick_reply
                        index: 0
                        parameters:
                          - type: payload
                            to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Campaign'
                type: object
      operationId: sendTemplateCampaign
      x-ai-role: chatbot_campaign_manager
      x-ai-description: >-
        Initiates a mass broadcast to all subscribers of a WhatsApp bot using a
        pre-approved template. Unlike free-form messages, WhatsApp Business
        requires approved templates for outbound campaigns — this endpoint is
        the primary mechanism for scheduled or immediate bulk outreach. Template
        selection, language match, and component substitution (variables,
        images, buttons) must be correct before sending, as failed campaigns
        cannot be recalled.
      x-ai-reasoning-instructions:
        - >-
          Verify the bot_id is valid and belongs to an active WhatsApp bot
          before constructing the request.
        - >-
          Check that the template name matches an approved template in the
          account — unapproved or misspelled template names will cause the
          campaign to fail silently or return an error.
        - >-
          If send_at is provided, validate the datetime format strictly as
          'Y-m-d H:i' (e.g., '2025-04-01 09:00'); incorrect format will prevent
          scheduling.
        - >-
          If components are included, ensure the type values ('header', 'body',
          'button') match the actual structure of the selected template —
          mismatched components cause API rejection.
        - >-
          For button components (type=button), sub_type and index are required;
          remind the user that index must be 0–2 and quick_reply requires a
          payload.
        - >-
          If the campaign is immediate (no send_at), warn the user that it will
          be dispatched to all subscribers instantly with no undo option.
        - Image links must use HTTPS — HTTP links will be rejected.
      x-ai-responding-instructions:
        - >-
          On success, confirm the campaign was queued or scheduled and surface
          the campaign ID from the response data for tracking.
        - >-
          If send_at was provided, explicitly state the scheduled dispatch time
          in a human-readable format.
        - >-
          If success is false, surface the error reason clearly and suggest
          corrective action (e.g., wrong template name, invalid bot_id,
          malformed component).
        - >-
          Remind the user that this sends to ALL bot subscribers — suggest using
          filters or segments if partial targeting was intended.
        - >-
          After a successful send, suggest checking campaign delivery stats via
          the campaigns list or analytics endpoints.
      x-ai-suggestions:
        - >-
          Use `send_at` to schedule campaigns during high-engagement hours
          (e.g., 10:00–12:00 local time).
        - >-
          Retrieve valid template names from the 'Templates' tab of the bot or
          via the templates API before calling this endpoint.
        - >-
          For personalized campaigns, populate `components[].parameters` with
          per-variable values matching template placeholders.
      x-ai-capabilities:
        confirmation:
          type: Required
          message: >-
            This will immediately send a message to ALL subscribers of the
            selected bot. Confirm before proceeding.
        security_info:
          data_handling:
            - MassBroadcast
            - IrreversibleAction
  /account:
    get:
      summary: Get account info
      description: >-
        Returns information about your current account pricing plan, the number
        of messages in your plan, bots, contacts, list of tags, and variables
      security:
        - oAuth2ClientCredentials: []
      tags:
        - account
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Account'
                type: object
      operationId: getAccount
      x-ai-role: account_manager
      x-ai-description: >-
        Provides a real-time snapshot of the account's current state: active
        pricing plan, remaining message quotas, connected bots, total contacts,
        and all defined tags and variables. Use this as the entry point before
        planning campaigns — quota limits directly determine what actions are
        feasible.
      x-ai-reasoning-instructions:
        - >-
          Call this endpoint first when the user asks about their plan, limits,
          or available resources.
        - >-
          Use quota fields to validate whether a planned bulk send or bot
          campaign is within the account's current limits before proceeding.
        - >-
          If tags or variables are returned, surface them to the user as
          available segmentation options for upcoming campaigns.
        - >-
          Cross-reference bot count against the user's intent — if they want to
          create a new bot but the limit is reached, flag this proactively.
      x-ai-responding-instructions:
        - >-
          Summarize the pricing plan name and key quotas (messages remaining,
          contacts, bots) in a human-readable format.
        - >-
          If quotas are low (e.g., <10% remaining), warn the user and suggest
          upgrading or optimizing usage.
        - >-
          List available tags and variables only if the user's intent involves
          segmentation or personalization.
        - >-
          Avoid dumping the full raw response — highlight what is actionable
          given the user's current goal.
      x-ai-suggestions:
        - >-
          Check this before scheduling a large email campaign to confirm message
          quota is sufficient.
        - >-
          Use returned variable names as valid merge tags when composing
          personalized messages.
        - >-
          If bot count equals the plan limit, advise the user to remove unused
          bots before creating new ones.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /templates:
    get:
      summary: Get a template list
      description: Returns a list of templates with information about each template
      security:
        - oAuth2ClientCredentials: []
      parameters:
        - in: query
          name: bot_id
          required: true
          schema:
            type: string
          description: >-
            The bot ID where the templates are located. 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:
        - templates
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Template'
                type: object
      operationId: getTemplateList
      x-ai-role: chatbot_content_manager
      x-ai-description: >-
        Retrieves all message templates configured for a specific bot. Templates
        are reusable content blocks that define the structure of outgoing
        messages — text, buttons, media — and serve as the foundation for
        campaigns and automated flows. Knowing which templates exist and their
        current state is essential before scheduling any broadcast or building a
        bot scenario.
      x-ai-reasoning-instructions:
        - >-
          Ensure a valid bot_id is provided — it is required and the request
          will fail without it.
        - >-
          Use the bot listing endpoint first if the bot_id is unknown or needs
          to be confirmed.
        - >-
          If the user wants to send a campaign, retrieve templates first to let
          them pick an existing one before suggesting creation of a new one.
        - >-
          Check whether returned templates are active/approved before
          recommending them for use in a flow.
      x-ai-responding-instructions:
        - >-
          Present the template list with names and IDs so the user can easily
          identify which one to use.
        - >-
          If the list is empty, suggest creating a new template as the next
          step.
        - >-
          If multiple templates exist, help the user filter by name or content
          type based on their goal.
        - >-
          Mention the bot context clearly so the user understands the results
          are scoped to one specific bot.
      x-ai-suggestions:
        - >-
          Use the returned template IDs with the send-campaign endpoint to
          launch a broadcast.
        - >-
          If no suitable template exists, proceed to create one with the
          template creation endpoint.
        - >-
          Cross-reference bot_id with the bot list if you are unsure which bot
          owns the desired templates.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
  /tags:
    get:
      summary: Get a list of tags
      description: >-
        Returns the list of created tags for the selected bot with information
        about each of them: tag ID, name, contact_count and creation date
      security:
        - oAuth2ClientCredentials: []
      tags:
        - tags
      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
          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
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
                type: object
      operationId: listTags
      x-ai-role: chatbot_audience_manager
      x-ai-description: >-
        Retrieves a paginated list of tags defined for a specific bot. Tags are
        labeling primitives used to segment contacts in the chatbot audience —
        understanding available tags is a prerequisite for any filtering,
        segmentation, or automated flow targeting by tag.
      x-ai-reasoning-instructions:
        - >-
          Always require bot_id before calling — without it the scope is
          undefined.
        - >-
          If the user needs to find a specific tag, retrieve the full list first
          and filter client-side, as there is no server-side name filter.
        - >-
          Use 'size' and 'skip' parameters for large bots; default batch may not
          return all tags.
        - >-
          Cross-reference contact_count to identify orphaned or unused tags that
          may be candidates for cleanup.
      x-ai-responding-instructions:
        - >-
          Present the result as a structured list: tag name, ID, and
          contact_count for each entry.
        - >-
          If contact_count is 0 for all returned tags, flag that the bot may
          have tags defined but no contacts assigned yet.
        - >-
          Suggest using a returned tag ID as input for contact filtering or flow
          targeting operations.
        - >-
          If the list is truncated (size limit reached), inform the user and
          suggest increasing 'size' or paginating with 'skip'.
      x-ai-suggestions:
        - >-
          Retrieve all tags first to map names to IDs before applying them to
          contacts.
        - >-
          Use contact_count to prioritize high-volume segments for campaign
          targeting.
        - >-
          Paginate with size=50 and increment skip to enumerate all tags for
          large bots.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ReadOnly
security:
  - apiKey: []
  - oauth2: []
servers:
  - description: ''
    url: https://api.sendpulse.com/whatsapp
tags:
  - description: ''
    name: account
  - description: ''
    name: bots
  - description: (subscribers)
    name: contacts
  - description: ''
    name: variables
  - description: ''
    name: flows
  - description: (keywords)
    name: triggers
  - description: ''
    name: chats
  - description: (broadcasts)
    name: campaigns
  - description: ''
    name: templates
