SendPulse Contacts messengers API

openapi: 3.2.0
info:
  description: Using the API for the CRM service, you can integrate your system with CRM from SendPulse and receive detailed information on pipelines, deals, contacts and their attributes and users.
  title: SendPulse CRM Public Contacts messengers API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Contacts messengers
paths:
  /contacts/{contactId}/messengers:
    post:
      tags:
      - Contacts messengers
      summary: Add messenger to contact
      description: Adds a messenger to the specified contact
      parameters:
      - name: contactId
        in: path
        required: true
        description: Contact ID you want to add a mesenger to. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                typeId:
                  $ref: '#/components/schemas/MessengerTypeProperty'
                login:
                  type: string
                  description: Contacts login in the specified messenger
                isMainChatbot:
                  type: boolean
                  description: Determine if chatbot messenger is the main one
              required:
              - typeId
              - login
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ContactMessenger'
      operationId: addContactMessenger
      x-ai-role: crm_integration_specialist
      x-ai-description: Links a specific messenger account (e.g., Telegram, WhatsApp, Viber) to an existing CRM contact. This creates a multi-channel communication profile, enabling chatbot automation and targeted messaging through the contact's preferred messenger. Designating a main chatbot messenger is critical for routing automated sequences correctly.
      x-ai-reasoning-instructions:
      - Verify the contactId exists before attempting to add a messenger — use 'Get a list of contacts' if the ID is unknown.
      - Check if the contact already has a messenger of the given typeId to avoid duplicates.
      - If isMainChatbot is true, be aware this may override the existing main chatbot messenger for the contact.
      - Validate that the login format matches the conventions of the specified messenger type (e.g., phone number for WhatsApp, username for Telegram).
      - Confirm the typeId value against the MessengerTypeProperty enum before sending the request.
      x-ai-responding-instructions:
      - Confirm success by referencing the contactId and the messenger type that was linked.
      - If isMainChatbot was set to true, explicitly note that this messenger is now the primary chatbot channel for the contact.
      - Suggest verifying the result by retrieving the contact's messenger list as a follow-up.
      - On error, clarify whether the issue is with the contactId (not found), typeId (unsupported), or login (invalid format).
      x-ai-suggestions:
      - After adding, use the messenger channel to enroll the contact in a chatbot flow.
      - If managing bulk contacts, iterate over a contact list and add messengers programmatically.
      - 'Set isMainChatbot: true only for the primary automation channel to avoid routing conflicts.'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ResourceStateUpdate
          - PersonalDataWrite
  /contacts/{contactId}/messengers/{messengerId}:
    put:
      tags:
      - Contacts messengers
      summary: Update information about messenger of the contact
      description: Updates information about a given messenger for the specified contact. Provided property values will be overwritten.
      parameters:
      - name: contactId
        in: path
        required: true
        description: Contact ID for which you want to update messenger information. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      - name: messengerId
        in: path
        required: true
        description: Messenger ID you want to update. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                typeId:
                  $ref: '#/components/schemas/MessengerTypeProperty'
                login:
                  type: string
                  description: Contacts login in the specified messenger
                isMainChatbot:
                  type: boolean
                  description: Determine if chatbot messenger is the main one
              required:
              - typeId
              - login
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ContactMessenger'
      operationId: updateContactMessenger
      x-ai-role: crm_integration_specialist
      x-ai-description: Updates a specific messenger entry linked to a contact. This is a partial-overwrite operation — only the fields you provide will be changed. Use this when a contact's messenger handle changes (e.g., new Telegram username) or when you need to promote a chatbot channel to 'main' for routing automation flows through it.
      x-ai-reasoning-instructions:
      - Before updating, confirm the contactId and messengerId are valid by calling 'Get a list of contacts' — both IDs must exist and be related.
      - The `typeId` and `login` fields are required — always validate both are present before sending.
      - If the goal is to change only `isMainChatbot`, still include `typeId` and `login` to satisfy the required constraint.
      - 'Only one messenger per contact can be the main chatbot — setting `isMainChatbot: true` here may implicitly demote another messenger; confirm this behavior with the user if relevant.'
      - Messenger `login` formats differ by type — ensure the login value matches the expected format for the given `typeId` (e.g., Telegram username vs. phone number for WhatsApp).
      x-ai-responding-instructions:
      - Confirm which fields were updated and on which contact/messenger combination.
      - If `isMainChatbot` was changed to true, notify the user that this messenger is now the primary chatbot channel for this contact.
      - Return the updated ContactMessenger object and highlight any fields that changed.
      - On 404 or invalid ID errors, suggest using 'Get a list of contacts' to retrieve valid contactId and messengerId values.
      x-ai-suggestions:
      - Use this after a contact reports a changed messenger handle to keep routing rules accurate.
      - Combine with 'Get a list of contacts' to build a bulk-update flow for stale messenger records.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: 'You are about to overwrite messenger data for contact #{contactId}. This action cannot be undone automatically.'
        security_info:
          data_handling:
          - ResourceStateUpdate
    delete:
      tags:
      - Contacts messengers
      summary: Remove messenger from contact
      description: Removes messenger from a specified contact
      parameters:
      - name: contactId
        in: path
        required: true
        description: Contact ID from which you want to remove messenger. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      - name: messengerId
        in: path
        required: true
        description: Messenger ID you want to remove. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      responses:
        '204':
          description: Successfully deleted
      operationId: removeContactMessenger
      x-ai-role: crm_integration_specialist
      x-ai-description: Permanently detaches a messenger channel from a contact record. Use when a contact opts out of a specific channel, changes their account, or when cleaning up stale/invalid messenger links. This action affects only the channel binding — the contact itself and other messengers remain intact.
      x-ai-reasoning-instructions:
      - Confirm the contactId is valid and the contact exists before attempting deletion.
      - Confirm the messengerId belongs to the specified contact — mixing IDs from different contacts will result in a 404 or unintended deletion.
      - Warn the user if this messenger is the contact's only communication channel, as removal will leave the contact unreachable.
      - This action is irreversible — the messenger link must be re-added manually if removed by mistake.
      x-ai-responding-instructions:
      - On success (204), confirm that the messenger has been unlinked from the contact.
      - Remind the user that the contact still exists and other messengers remain unaffected.
      - If the intent was to remove all messengers, suggest iterating over the full messenger list from 'Get a list of contacts'.
      - On error, clarify whether the issue is with the contactId or the messengerId.
      x-ai-suggestions:
      - Use 'Get a list of contacts' to retrieve both contactId and messengerId before calling this endpoint.
      - After removal, verify the contact's remaining channels to ensure reachability.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: This will permanently remove the messenger link from the contact. Proceed?
        security_info:
          data_handling:
          - ResourceDeletion
components:
  schemas:
    ContactMessenger:
      type: object
      properties:
        id:
          type: integer
          description: ID of the added messenger
        typeId:
          type: integer
          description: Messenger type
        login:
          type: string
          description: Contact login in the specified messenger
        botId:
          type: string
          description: External bot ID
        contactId:
          type: string
          description: External contact ID
        status:
          type: integer
        chatbotUrl:
          type: string
          description: URL of the chatbot from which the contact was received
        isMainChatbot:
          type: boolean
          description: Determine if chatbot messenger is the main one
    MessengerTypeProperty:
      type: integer
      description: '| Messenger type. Possible values: * 1 — Telegram * 2 — Facebook * 4 — Instagram * 5 — WhatsApp * 6 — Viber'
  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.

        '