openapi: 3.2.0 info: title: Sendpulse Contacts API x-refined-note: - x-ai-description differs across the merged source definitions and was not carried version: '1.0' description: 'Operations tagged Contacts across 9 of this provider''s published API definitions: sendpulse-crm-openapi.yml, sendpulse-facebook-openapi.yml, sendpulse-instagram-openapi.yml, sendpulse-live-chat-openapi.yml, sendpulse-sms-openapi.yml, sendpulse-telegram-openapi.yml, sendpulse-tiktok-openapi.yml, sendpulse-viber-chatbot-openapi.yml, sendpulse-whatsapp-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.sendpulse.com/crm/v1 - description: '' url: https://api.sendpulse.com/messenger - description: '' url: https://api.sendpulse.com/instagram - description: '' url: https://api.sendpulse.com/live-chat - url: https://api.sendpulse.com - description: '' url: https://api.sendpulse.com/telegram - description: '' url: https://api.sendpulse.com/tiktok - description: '' url: https://api.sendpulse.com/viber/chatbots - description: '' url: https://api.sendpulse.com/whatsapp security: - apiKey: [] - oauth2: [] tags: - description: '' name: Contacts paths: /contacts/get-list: post: tags: - Contacts summary: Get contacts list requestBody: content: application/json: schema: properties: limit: type: integer minimum: 1 maximum: 100 offset: type: integer minimum: 0 from: type: string format: date description: Contact creation date, filter start date. Accepted format YYYY-MM-DD to: type: string format: date description: Contact creation date, filter end date. Accepted format YYYY-MM-DD updateFrom: type: string format: date description: Contact updated date, filter start date. Accepted format YYYY-MM-DD updateTo: type: string format: date description: Contact updated date, filter end date. Accepted format YYYY-MM-DD firstName: type: string description: Contacts first name you want to search for lastName: type: string description: Contacts last name you want to search for responsibleIds: type: array description: A list with the ID of users assigned to the contact you want to to search for. It can be obtained with the "Get a list of team members" method items: type: integer sourceType: type: array items: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 8 - 9 - 10 phone: type: string description: Phone number of a contact email: type: string tagIds: type: array items: type: integer messengerTypeIds: type: array items: type: integer messengerLogin: type: string sortBy: type: object properties: direction: type: string description: 'Sorting direction. Possible values: asc — ascending order; desc — descending order.' enum: - asc - desc fieldName: type: string enum: - id - created_at - first_name - attributeId - responsible_id example: id attributes: $ref: '#/components/schemas/AttributesProperty' location: type: string fieldValueConditions: type: array items: type: object properties: field: type: string description: Field name enum: - attributes - lastName - phones - emails - messengers - location - tags expression: type: string description: '| Possible values: - eq (=) - neq (!=) - gt (>) - gte (>=) - lt (<) - lte (<=) - like - in (check among list of values).' value: description: Can have array or string type ids: type: array description: Array of contacts IDs items: type: integer responses: '200': description: '' content: application/json: schema: properties: data: properties: list: items: $ref: '#/components/schemas/Contact' total: type: integer searchRequest: type: string operationId: getContactsList x-ai-role: crm_data_analyst x-ai-description: Powerful filtered search across the CRM contact base. Unlike a simple list fetch, this endpoint supports multi-dimensional filtering — by creation/update date ranges, assigned team members, source types, tags, messengers, custom attributes, and field-level conditions. Used to build segmented views, audit contact data, or feed downstream automation with a precise contact subset. x-ai-reasoning-instructions: - Combine filters additively — all provided conditions are applied simultaneously (AND logic), so overly specific combinations may return empty results. - Use `from`/`to` for filtering by creation date and `updateFrom`/`updateTo` for recently modified contacts — do not mix up the two date ranges. - When filtering by `responsibleIds`, first call 'Get a list of team members' to resolve names to IDs. - Paginate using `limit` (max 100) and `offset` — for large datasets, iterate until `total` is exhausted. - If `fieldValueConditions` is used, ensure `field` names match the schema enum — typos cause silent empty results. - For sorting by a custom attribute, use `attributeId` as `fieldName` and provide the actual attribute ID. - When the user describes a search intent in natural language, map it to the most specific available filters before falling back to broad ones. x-ai-responding-instructions: - Report the total count from `searchRequest` or `total` field alongside the list — it helps the user understand whether they got all results or need to paginate. - If the result list is empty, suggest reviewing the filter combination — one overly restrictive condition is often the cause. - When returning a subset of a large dataset, remind the user to paginate with `offset` to retrieve remaining records. - If the user searched by a specific filter (e.g., tag, responsible), confirm which filter was applied and how many contacts matched. x-ai-suggestions: - Filter contacts created in the last 30 days using `from`/`to` date range. - Use `tagIds` + `messengerTypeIds` together to find contacts reachable via a specific channel with a given tag. - Sort by `created_at` descending to get the newest contacts first. - 'Use `fieldValueConditions` with `expression: like` for partial name/email matching when exact values are unknown.' x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts/get-list-by-email: post: tags: - Contacts summary: Search contacts by email description: 'Returns contacts and the following information about each: the contact ID, the assigned person and the contact information' requestBody: content: application/json: schema: properties: email: type: string description: Email address of a contact isEmailFullSearch: type: boolean description: Search for emails that match completely or partially (true/false) responses: '200': description: '' content: application/json: schema: properties: data: properties: list: description: List with contacts type: array items: $ref: '#/components/schemas/Contact' total: description: Total number of filtered records for pagination type: integer operationId: getContactListByEmail x-ai-role: crm_data_analyst x-ai-description: Performs a lookup of CRM contacts by email address, returning full contact records including assigned responsible persons and contact details. Useful for deduplication checks, pre-call research, and verifying whether a lead already exists before creating a new one. The partial-match mode makes it effective for domain-level searches (e.g., finding all contacts from a company). x-ai-reasoning-instructions: - If the user provides a full email address, default isEmailFullSearch to true to avoid unrelated results. - When the user wants to find all contacts from a domain (e.g., '@company.com'), set isEmailFullSearch to false for partial matching. - Before creating a new contact, suggest running this search first to prevent duplicates. - Use the returned total field to determine if pagination is needed — if total exceeds the returned list size, advise the user to paginate. x-ai-responding-instructions: - Report how many contacts were found (use the total field, not the list length). - If a single exact match is found, surface the contact ID and assigned person prominently. - 'If no contacts are found, suggest trying partial search (isEmailFullSearch: false) or verifying the email spelling.' - If multiple contacts are returned, summarize them as a list with ID, name, and assigned person. x-ai-suggestions: - 'Use isEmailFullSearch: false to find all contacts sharing an email domain.' - Combine results with getContact to retrieve full contact details by ID. - Run this before createContact to enforce uniqueness within the CRM. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts: post: deprecated: true tags: - Contacts summary: (Deprecated). Use POST /contacts/create instead to create a new contact description: Creates a contact with the given properties and returns a copy of the information, including the ID requestBody: content: application/json: schema: properties: responsibleId: type: integer description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method firstName: type: string description: Contact first name lastName: type: string description: Contact last name phones: type: array description: List of phone numbers in the international format items: type: string emails: type: array description: List of email addresses items: type: string tags: type: array description: List of tag IDs to be added to a contact. It can be obtained with the "Get a list of contact tags" method items: type: integer attributes: type: array description: 'List of fields to add to the contact. Pass in the attributes field array an object with the attributeId and value fields (will create a contact with an already existing attribute) Pass in the attributes field array an object with the name, type , value fields (will create a contact with a new attribute if there is no such attribute yet or create a contact with an existing attribute if the attribute already exists)'' ' items: properties: name: type: string description: Attribute name value: type: string description: Attribute value type: type: integer description: 0 - text, 1 - number, 2 - date, 3 - link, 4 - select , 5 - multiSelect required: - name - value messengers: type: array description: List of messengers to add to a contact items: properties: typeId: $ref: '#/components/schemas/MessengerTypeProperty' login: type: string description: Contacts login in the specified messenger required: - typeId - login attachments: type: array items: type: string description: First, the file must be uploaded to the file manager, and then the file can be attached. example: - /personal/deal/sendPulse_crm_deals.csv required: - responsibleId responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/Contact' operationId: createContact x-ai-role: crm_data_entry_specialist x-ai-description: Deprecated endpoint for creating a CRM contact with full profile data including phones, emails, messengers, custom attributes, and file attachments. Replaced by POST /contacts/create — use that instead for all new integrations. This endpoint remains for backward compatibility only. x-ai-reasoning-instructions: - This endpoint is deprecated — always redirect the user to POST /contacts/create unless they explicitly need backward compatibility. - Before creating, consider checking for duplicate contacts by phone or email to avoid data pollution in the CRM. - The `responsibleId` is required — ensure the team member ID is obtained via the 'Get a list of team members' method before calling. - For `attributes`, clarify whether existing attributes (by `attributeId`) or new ones (by `name`+`type`) are intended — the behavior differs. - File attachments must be pre-uploaded via the file manager; raw file data cannot be passed directly. - Messenger `typeId` must reference a valid enum value — confirm the correct messenger type before constructing the payload. x-ai-responding-instructions: - Warn the user that this endpoint is deprecated and recommend migrating to POST /contacts/create. - On success, highlight the new contact ID from the returned `data.Contact` object. - If attributes were created as new (by name), note that they are now persistent CRM attributes shared across contacts. - Suggest following up with assigning the contact to a deal or pipeline stage as a next logical step. x-ai-suggestions: - Use POST /contacts/create for all new contact creation workflows. - Retrieve valid `responsibleId` values via GET /team before calling this endpoint. - Retrieve valid tag IDs via GET /contacts/tags before assigning tags. x-ai-capabilities: confirmation: type: Recommended message: Creating a contact will persist it in the CRM and may trigger automations or assignments. security_info: data_handling: - ResourceStateCreate - PersonalDataStorage servers: - url: https://api.sendpulse.com/crm/v1 /contacts/create: post: tags: - Contacts summary: Create a new contact description: Creates a contact requestBody: content: application/json: schema: properties: responsibleId: type: integer description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method firstName: type: string description: Contact first name lastName: type: string description: Contact last name externalContactId: type: string description: External contact ID field for services data - we do not recommend using it to add an ID from third-party systems required: - responsibleId responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/Contact' operationId: createContact x-ai-role: crm_specialist x-ai-description: Initializes a new contact record in the CRM. A contact is the foundational entity in SendPulse CRM — assigning a responsible team member at creation time ensures immediate ownership and enables automated routing, task assignment, and follow-up pipelines from the first interaction. x-ai-reasoning-instructions: - Before creating, verify the responsibleId is valid by cross-referencing with the 'Get a list of team members' endpoint. - Avoid using externalContactId for third-party system IDs as it is not recommended — suggest alternative approaches if the user intends to map external records. - If both firstName and lastName are omitted, warn the user that the contact will be anonymous, which may hinder identification later. - Check whether a contact with the same name or external ID might already exist to prevent duplicates. x-ai-responding-instructions: - Confirm creation by surfacing the new contact's ID from the returned Contact object. - Suggest populating the contact with additional data (phone, email, deals) as an immediate next step. - If the responsibleId is invalid, explain that the value must come from the team members list and guide the user to retrieve it. x-ai-suggestions: - Use 'Get a list of team members' to obtain a valid responsibleId before calling this endpoint. - After creation, use 'Create a deal' to associate a sales opportunity with the new contact. - Consider adding tags or custom fields immediately after creation to enrich the contact profile. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate - PersonalDataStorage servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}: get: tags: - Contacts summary: Get information about a contact by ID description: 'Returns the following information on the specified contact: ID, team member responsible for the contact, first and Contacts last name, number of deals of the contact, list of phone numbers and email addresses, and messengers of the contact' parameters: - name: contactId in: path required: true description: Contact ID for which you want to get information. It can be obtained with the "Get a list of contacts" method schema: type: integer responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/Contact' operationId: getContactById x-ai-role: crm_data_analyst x-ai-description: Retrieves a complete profile of a single CRM contact by their unique ID. This is the primary lookup endpoint for building contact detail views, pre-filling forms before edits, or resolving a contact reference obtained from a list or deal. The response aggregates identity, ownership, communication channels, and deal history into one call — avoiding multiple round-trips. x-ai-reasoning-instructions: - Ensure the contactId was obtained from a trusted source such as `getContacts` or a deal's contact reference — do not guess or construct IDs. - If the previous call returned a list, extract the correct ID before calling this endpoint. - Check whether the caller needs only basic identity info or full channel data; this endpoint returns both, so no supplemental calls are needed. - If the response is needed to pre-fill an edit form, cache it locally to avoid redundant requests. x-ai-responding-instructions: - Present the contact's full name, responsible team member, and contact channels (phone, email, messengers) in a structured, readable format. - Highlight the number of associated deals to give the user a quick sense of the contact's activity level. - If the contact has multiple phone numbers or emails, list all of them clearly — do not omit secondary entries. - Suggest logical next steps such as updating the contact, viewing associated deals, or initiating communication. x-ai-suggestions: - Use `getContacts` first to search by name or email and obtain the contactId. - After retrieving the contact, you can update their data with the corresponding PATCH /contacts/{contactId} endpoint. - To see deals linked to this contact, query the deals endpoint filtered by this contactId. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly put: tags: - Contacts summary: Update information about the contact description: Update information about specified contact parameters: - name: contactId in: path required: true description: Contact ID of the contact whose information 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: responsibleId: type: integer description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method firstName: type: string description: Contact first name lastName: type: string description: Contact last name required: - responsibleId responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/Contact' operationId: updateContact x-ai-role: crm_data_steward x-ai-description: Updates mutable fields of an existing CRM contact record. This is the primary mutation endpoint for keeping contact profiles accurate — ownership reassignment (responsibleId) is mandatory, making it suitable for both data corrections and responsibility handoffs between team members. x-ai-reasoning-instructions: - Retrieve the contactId first via 'Get a list of contacts' if not already known — never guess or fabricate IDs. - responsibleId is required; confirm the target team member exists via 'Get a list of team members' before calling. - If only name fields are changing, still supply the current responsibleId to avoid unintended ownership transfer. - Warn the user if they are reassigning a contact to a different team member, as this affects pipeline visibility and notifications. x-ai-responding-instructions: - Confirm which fields were updated and reflect the new values back to the user. - If responsibleId changed, explicitly mention the ownership transfer and to whom. - Suggest fetching the updated contact via 'Get contact details' to verify the full record state. - On 404, clarify that the contactId may be invalid or the contact may have been deleted. x-ai-suggestions: - Use 'Get a list of team members' to resolve a name to a valid responsibleId before calling. - Combine with 'Get a list of contacts' to batch-update contacts by segment. x-ai-capabilities: confirmation: type: Recommended message: Confirm before reassigning contact ownership, as it affects team workload distribution. security_info: data_handling: - ResourceStateUpdate delete: tags: - Contacts summary: Remove contact by ID description: Removes the specified contact by ID parameters: - name: contactId in: path required: true description: Contact ID to be removed. It can be obtained with the "Get a list of contacts" method schema: type: integer responses: '204': description: Successfully deleted operationId: deleteContactById x-ai-role: crm_data_steward x-ai-description: Permanently removes a contact record from the system by its unique identifier. This is a hard-delete operation — the contact and all associated data (tags, custom fields, activity history) are irreversibly erased. Use when a contact explicitly opts out under GDPR/CCPA or when cleaning up test/duplicate records. x-ai-reasoning-instructions: - Before deleting, confirm with the user that this is intentional — deletion is irreversible and cannot be undone. - Verify the contactId exists by calling the 'Get a list of contacts' method if the ID was not obtained in the current session. - Check whether the contact is currently enrolled in active automations or campaigns — deletion mid-flow may cause broken sequences. - If the intent is GDPR/CCPA erasure, ensure this call is part of a broader data-removal workflow (e.g., also remove from mailing lists). x-ai-responding-instructions: - Confirm deletion with the contactId that was removed. - Remind the user that this action is permanent and the contact cannot be restored. - If the use case is compliance-driven, suggest verifying removal across all related resources (lists, automations, CRM deals). - On 404, clarify that the contact may have already been deleted or the ID is incorrect. x-ai-capabilities: confirmation: type: Required message: 'This will permanently delete contact #{contactId}. This action cannot be undone.' security_info: data_handling: - IrreversibleDelete - PiiDataRemoval servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/deals: get: tags: - Contacts summary: Get all deals that related to contact parameters: - name: contactId in: path required: true schema: type: integer responses: '200': description: deals list content: application/json: schema: properties: data: items: $ref: '#/components/schemas/Deal' operationId: getContactDeals x-ai-role: crm_sales_analyst x-ai-description: Retrieves the full list of deals associated with a specific contact, providing a 360-degree view of the sales relationship. Use this to assess pipeline health for an individual contact, identify stalled deals, or understand a contact's purchase history before outreach. x-ai-reasoning-instructions: - Verify the contactId is valid before calling — an incorrect ID returns an empty dataset or 404, not an error. - Consider whether the user wants all deals or a filtered subset; this endpoint returns all, so post-filter by status if needed. - If the result set is empty, distinguish between 'contact exists but has no deals' and 'contact not found' scenarios for the user. x-ai-responding-instructions: - Summarize the deals by status (e.g., open, won, lost) rather than listing raw data. - Highlight any deals in critical stages (e.g., negotiation, closing) that may require immediate action. - If no deals are found, suggest creating a deal with the relevant create-deal endpoint. x-ai-suggestions: - Use the returned deal IDs to fetch individual deal details or update deal stages. - Cross-reference with contact activity to prioritize follow-ups on stalled deals. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/comments: post: tags: - Contacts summary: Add a note to a contact description: Adds a note to the specified contact parameters: - name: contactId in: path required: true description: Contact ID to which you want to add a note. It can be obtained with the "Get a list of contacts" method schema: type: integer requestBody: content: application/json: schema: properties: message: type: string minLength: 1 description: Note message. The maximum number of characters is 65,535 required: - message responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/ContactComment' operationId: addContactComment x-ai-role: crm_relationship_manager x-ai-description: Adds a persistent internal note to a specific CRM contact. Notes serve as a chronological communication log visible only to team members — not the contact — enabling context sharing between agents, support staff, and sales reps across interactions. x-ai-reasoning-instructions: - Verify the contactId is valid before submitting — use 'Get a list of contacts' if the ID is uncertain. - Notes are internal only; never use this endpoint to send a message to the contact. - Ensure the message is meaningful and actionable — generic notes reduce CRM signal quality. - Check that the message length does not exceed 65,535 characters before sending. x-ai-responding-instructions: - Confirm the note was added successfully and reference the contact it was attached to. - If the contactId is not found, suggest retrieving the correct ID via the contacts list endpoint. - Suggest adding follow-up notes or scheduling a task as a logical next step. x-ai-suggestions: - Called on 2024-03-15, expressed interest in premium plan — follow up next week. - 'Support ticket #4821 resolved. Customer confirmed satisfaction.' - Do not send promotional emails — opted out verbally during call. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/comments/{commentId}: put: tags: - Contacts summary: Update contact note description: Updates the note of the specified contact. Provided property values will be overwritten. parameters: - name: contactId in: path required: true description: Contact ID contact for which you want to update the note. It can be obtained with the "Get a list of contacts" method schema: type: integer - name: commentId in: path required: true description: Note 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: message: type: string minLength: 1 description: New note message. The maximum number of characters is 65,535 required: - message responses: '200': description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/ContactComment' operationId: updateContactComment x-ai-role: crm_data_quality_specialist x-ai-description: 'Updates the text of an existing note attached to a specific contact. Notes (comments) serve as internal team annotations — sales context, call outcomes, follow-up reminders. Overwriting is full replacement: any prior text is lost, so this action should be used deliberately.' x-ai-reasoning-instructions: - Confirm the contactId and commentId are valid before sending — both can be retrieved from the 'Get a list of contacts' response. - Since the update fully overwrites the existing message, ask the user to confirm they have the current note content if they want to append rather than replace. - Check that the message does not exceed 65,535 characters before sending to avoid a validation error. - If the intent is to delete a note rather than update it, inform the user that a dedicated delete endpoint may exist. x-ai-responding-instructions: - Confirm success by referencing the contactId and commentId that were updated. - If the user appended text to the old note, remind them the old content is no longer stored. - Suggest reviewing the contact's full note history if multiple comments are being managed. x-ai-suggestions: - Spoke with client on 2024-03-20, moved to negotiation stage. - Follow-up scheduled for next week. Awaiting procurement approval. - Corrected entry — previous note contained outdated information. x-ai-capabilities: confirmation: type: Recommended reason: Fully overwrites the existing note — previous content is permanently lost. security_info: data_handling: - ResourceStateUpdate - IrreversibleOverwrite delete: tags: - Contacts summary: Remove contact note description: Removes a note of a specified contact parameters: - name: contactId in: path required: true description: Contact ID for which you want to remove the note. It can be obtained with the "Get a list of contacts" method schema: type: integer - name: commentId in: path required: true description: Note 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: deleteContactComment x-ai-role: crm_data_steward x-ai-description: Permanently removes a specific note from a contact record. Notes store contextual history added by agents or users — deletion is irreversible and should be used for privacy cleanup, data correction, or removal of stale context that could mislead future interactions. x-ai-reasoning-instructions: - Confirm both contactId and commentId before proceeding — there is no recovery after deletion. - Check whether the note is referenced in any recent activity log or workflow before removing. - If the user wants to 'clear all notes', warn that this endpoint removes only one note at a time — loop carefully. x-ai-responding-instructions: - Confirm deletion by echoing both the contactId and commentId that were removed. - Mention that the action is irreversible and no backup exists. - Suggest using 'Get a list of contacts' to verify the note no longer appears if confirmation is needed. x-ai-capabilities: confirmation: type: Recommended message: This will permanently delete note {commentId} from contact {contactId}. This action cannot be undone. security_info: data_handling: - IrreversibleDelete servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/edu-payments: get: tags: - Contacts summary: Get EDU payments by contact parameters: - name: contactId in: path required: true schema: type: integer responses: '200': description: OK content: application/json: schema: properties: data: type: object properties: list: type: array items: type: object properties: courseId: type: integer name: type: string price: type: object properties: amount: type: integer currency: type: string status: type: integer paymentMethod: type: string enum: - YooMoney - PayPal - Fondy - ROBOKASSA - Stripe - MERCADOPAGO - LiqPay createdAt: type: string format: date-time operationId: getContactEduPayments x-ai-role: edu_payments_analyst x-ai-description: Retrieves the full payment history for a specific contact within the EDU module. Each record reflects a course purchase attempt or completion, including payment method, amount, currency, and current status. Use this to audit monetization activity per learner, detect failed or pending transactions, and inform support decisions. x-ai-reasoning-instructions: - Verify the contactId belongs to a valid CRM contact before calling — invalid IDs return empty or error. - The `status` field is an integer enum; map it to human-readable labels (e.g., 0=pending, 1=completed, 2=failed) using domain knowledge or supplementary documentation. - If the list is empty, it may mean the contact has not made any EDU purchases — not that the endpoint failed. - When analyzing payments, group by courseId to detect duplicate purchases or retry patterns. x-ai-responding-instructions: - Summarize the total number of payments found and highlight any non-completed statuses. - Present price as a formatted value with currency (e.g., '500 UAH', '9.99 USD'). - If multiple payment methods are present, note the variety — it may indicate cross-region usage. - Suggest follow-up actions such as checking course enrollment status or issuing a refund if failed payments are detected. x-ai-suggestions: - Use alongside `getContact` to build a complete learner profile with purchase history. - Filter results by `status` to identify contacts with failed payments for re-engagement campaigns. - Cross-reference `courseId` with the course catalog to enrich payment data with course names and categories. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly - PII — contact financial data, handle according to data privacy policy servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/edu-statistic: get: tags: - Contacts summary: Get EDU statistics for a contact parameters: - name: contactId in: path required: true schema: type: integer responses: '200': description: OK content: application/json: schema: properties: data: type: object properties: courses: type: array items: type: object properties: id: type: integer status: type: string statusStudentOnCourse: type: string sections: type: array items: type: object properties: id: type: integer name: type: string lessons: type: array items: type: object properties: id: type: integer name: type: string statusStudentOnLesson: type: object properties: status: type: string updatedAt: type: string tests: type: array items: type: object properties: name: type: string score: type: string operationId: getContactEduStatistic x-ai-role: edu_progress_analyst x-ai-description: Retrieves a full snapshot of a contact's educational journey within the EDU platform — including course enrollment statuses, section/lesson completion, and test scores. This is the primary endpoint for auditing individual learning progress, identifying blockers, and triggering re-engagement flows based on actual study behavior. x-ai-reasoning-instructions: - Verify that the contactId belongs to a contact enrolled in at least one EDU course before interpreting empty results as an error. - Distinguish between course-level status (e.g., 'active', 'completed') and student-on-course status — they may reflect different lifecycle states. - When analyzing lesson progress, check statusStudentOnLesson.updatedAt to assess recency of activity and identify stalled learners. - Test scores are returned as strings — handle potential null or non-numeric values before performing comparisons or aggregations. x-ai-responding-instructions: - Summarize overall progress per course before diving into section/lesson details. - Highlight any lessons or sections where progress has stalled (no recent updatedAt activity). - If test scores are available, present them alongside pass/fail context if thresholds are known. - If the response contains no courses, clarify that the contact may not be enrolled in any EDU courses rather than implying an error. x-ai-suggestions: - Use this endpoint before sending a re-engagement email to check if the contact is genuinely inactive. - Combine with contact profile data to build personalized course completion reports. - Cross-reference statusStudentOnCourse with lesson-level statuses to detect partial completions. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts/external/{externalContactId}: get: tags: - Contacts summary: Get contact exists by external contact Id parameters: - name: externalContactId in: path required: true description: External contact id from another source system schema: type: integer responses: '200': description: '' content: application/json: schema: properties: data: properties: data: $ref: '#/components/schemas/Contact' operationId: getContactByExternalId x-ai-role: crm_integration_specialist x-ai-description: Looks up a SendPulse contact using an ID from an external system (e.g., your CRM, e-commerce platform, or data warehouse). This is the bridge endpoint for cross-system identity resolution — it lets you avoid storing SendPulse-internal IDs in your own database by querying via the ID you already own. x-ai-reasoning-instructions: - Use this endpoint when the caller has an external system ID but not the SendPulse contact ID. - If the response returns no contact, suggest verifying that the external ID was previously linked during contact creation or update. - Prefer this over a full contact search when the external ID mapping is known — it is more precise and avoids pagination overhead. - Consider caching the resolved SendPulse contact ID on your side to reduce repeated lookups. x-ai-responding-instructions: - Return the resolved contact object and highlight the SendPulse contact ID for the user. - If the contact is not found (404 or empty data), explain that the external ID may not have been mapped in SendPulse yet. - Suggest follow-up actions such as updating contact data or triggering a flow based on the resolved contact. x-ai-suggestions: - Use the returned contact ID with `updateContact` to sync field changes from your source system. - If the contact is not found, use `createContact` with the same externalContactId to establish the mapping. - Chain with `getContactDeals` or `getContactTasks` for a full CRM context view. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts/messenger-external/{messengerContactId}: get: tags: - Contacts summary: Get contact by messenger contact id parameters: - name: messengerContactId in: path required: true description: External contact id from messenger schema: type: string responses: '200': description: '' content: application/json: schema: properties: data: properties: data: $ref: '#/components/schemas/Contact' operationId: getContactByMessengerExternalId x-ai-role: crm_integration_specialist x-ai-description: Resolves a CRM contact record using a messenger-side identifier. This is the bridge endpoint between external chat platforms (e.g., Telegram, Facebook Messenger) and the SendPulse CRM — use it when you have a messenger user ID but need the full CRM contact profile to read history, tags, or custom fields. x-ai-reasoning-instructions: - Use this endpoint when the available identifier is a messenger contact ID, not a CRM-native contact ID. - Verify that the messengerContactId originates from a connected messenger integration; unregistered IDs will return 404. - If the goal is to enrich or update the contact after lookup, follow up with a PATCH/PUT contact endpoint using the returned CRM contact ID. x-ai-responding-instructions: - Confirm which contact was resolved by referencing their name or email from the response. - If the contact is not found, clarify that the messenger contact may not be linked to any CRM record yet and suggest triggering a conversation flow to capture it. - Surface the internal CRM contact ID from the response so the user can reference it in subsequent operations. x-ai-suggestions: - After retrieving the contact, use the CRM contact ID to fetch their deal pipeline or tag history. - If lookup fails, consider using the contact search endpoint with messenger channel filters as a fallback. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - url: https://api.sendpulse.com/crm/v1 /contacts/{contactId}/relation/{companyId}: post: tags: - Contacts summary: Add contact to a company parameters: - name: contactId in: path required: true description: Contact ID you want to add to the company. It can be obtained with the "Get a list of contacts" method schema: type: integer - name: companyId in: path required: true description: Company ID you want to add to the contact. It can be obtained with the "Get a list of company" method schema: type: integer responses: '200': description: Contact successfully added to a company operationId: addContactCompanyRelation x-ai-role: crm_relationship_manager x-ai-description: Establishes a many-to-one relationship between a contact and a company in the CRM graph. This is not just a tag — it links the contact to the company's hierarchy, enabling company-level analytics, bulk actions, and deal attribution across all contacts belonging to that company. x-ai-reasoning-instructions: - Verify that both contactId and companyId exist before attempting to link — use 'Get a list of contacts' and 'Get a list of company' to resolve IDs if only names are provided. - Check whether the contact is already linked to this company to avoid duplicate relation requests. - If linking multiple contacts to the same company, consider whether a bulk operation is available instead of sequential calls. x-ai-responding-instructions: - Confirm the relation was created by restating which contact was linked to which company. - Suggest following up with 'Get contact details' to verify the updated company association. - If either ID is invalid or the relation already exists, explain clearly and offer to look up the correct IDs. x-ai-suggestions: - Use 'Get a list of contacts' to find contactId by name or email before calling this endpoint. - Use 'Get a list of company' to resolve companyId by company name. - After linking, consider updating the contact's role or deal stage within that company. x-ai-capabilities: confirmation: type: Recommended message: 'You are about to link contact #{contactId} to company #{companyId}. Confirm?' security_info: data_handling: - RelationshipCreate delete: tags: - Contacts summary: Delete a contact from the company parameters: - name: contactId in: path required: true description: Contact ID you want to delete from the company. It can be obtained with the "Get a list of contacts" method schema: type: integer - name: companyId in: path required: true description: Company ID you want to delete from the contact. It can be obtained with the "Get a list of company" method schema: type: integer responses: '200': description: Contact successfully deleted from the company operationId: deleteContactCompanyRelation x-ai-role: crm_relationship_manager x-ai-description: Removes the association between a specific contact and a company in the CRM. This is a structural operation that affects the contact's organizational affiliation — it does not delete the contact or the company, only the link between them. Use when a contact changes employer, leaves a company, or was incorrectly assigned. x-ai-reasoning-instructions: - Before proceeding, confirm that both the contactId and companyId are valid and that the relation actually exists — otherwise the operation may fail silently or return a misleading error. - 'Warn the user that this is irreversible: the relation must be re-created manually if removed by mistake.' - If the intent is to reassign the contact to a different company, advise creating the new relation first before deleting this one. x-ai-responding-instructions: - Confirm that the contact has been successfully unlinked from the company, mentioning both IDs. - Clarify that neither the contact nor the company record was deleted — only the relationship was removed. - Suggest verifying the contact's current company associations using 'Get a list of contacts' if the user needs to confirm the resulting state. x-ai-suggestions: - Use 'Get a list of contacts' to retrieve the contactId before calling this endpoint. - Use 'Get a list of company' to retrieve the companyId before calling this endpoint. - After deletion, consider creating a new relation if the contact should be linked to a different company. x-ai-capabilities: confirmation: type: Recommended message: This will permanently remove the contact-company association. Proceed? security_info: data_handling: - RelationshipDeletion servers: - url: https://api.sendpulse.com/crm/v1 /contacts/get: get: summary: Get contact info via a contact ID description: 'Returns information on the selected contact: bot and contact ID, information from Facebook, 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_2' type: object operationId: getContact x-ai-role: crm_data_analyst x-ai-description: Retrieves a complete profile snapshot of a single chatbot contact by their internal ID. This is the authoritative source for contact state — combining identity data from the connected platform (e.g. Facebook), enriched variables, tags, and engagement history. Use this before personalizing messages or evaluating automation eligibility. x-ai-reasoning-instructions: - Ensure the contact ID is valid and was obtained from a prior search or account UI — it is not the same as a platform user ID. - If the upstream intent is to personalize a message, fetch this endpoint first to verify current variable values and tag state. - If the response returns no data or a 404-equivalent, suggest the user verify the contact ID or search by tag/variable instead. x-ai-responding-instructions: - 'Surface the most actionable fields first: contact ID, bot ID, tags, and variables.' - If activity data is present, highlight last-seen or last-interaction timestamp to give context on contact engagement. - If the contact has no tags or variables, suggest adding them as a next step for segmentation. x-ai-suggestions: - Use the returned tag list to evaluate which automation flows this contact is eligible for. - Cross-reference variables with campaign conditions before triggering a sequence. - If you need to find the contact ID, use a contact search by tag or variable first. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - description: '' url: https://api.sendpulse.com/messenger /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_2' type: object operationId: getContactsByTag x-ai-role: chatbot_audience_analyst x-ai-description: Retrieves a filtered subset of bot contacts grouped by a specific tag. Tags in SendPulse chatbots act as behavioral or segmentation labels assigned during flows or manually. This endpoint is the primary way to build targeted audiences for broadcast campaigns, re-engagement flows, or CRM export — without iterating over the full contact list. x-ai-reasoning-instructions: - Before calling, confirm the bot_id is valid by cross-referencing with the list of available bots. - Ensure the tag value matches exactly — tags are case-sensitive and must already exist on at least one contact. - If the user wants all contacts with a tag, omit 'size' and 'skip' on first call, then paginate if the result set is large. - Use 'skip' + 'size' for pagination — calculate total pages based on result count vs. requested size. - If 0 contacts are returned, suggest verifying the tag spelling or checking whether contacts were tagged via the correct flow. x-ai-responding-instructions: - Report the number of contacts returned and whether pagination is likely needed. - If the list is empty, suggest checking tag assignment logic in the bot flow. - Highlight key contact fields (e.g., ID, name, last activity) to orient the user. - Suggest follow-up actions such as sending a broadcast to this segment or exporting to CRM. x-ai-suggestions: - Use this endpoint to build a segment before triggering a targeted broadcast. - Combine with pagination (size=50, skip=0) for large tag audiences. - Tag names like 'vip', 'trial_expired', or 'webinar_registered' are common segmentation patterns. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/getByVariable: get: summary: Get a list of contacts by variable description: Returns a list of 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 - in: query name: variable_name schema: type: string description: Сontact variable name to search by - in: query name: bot_id 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: 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_2' type: object operationId: getContactsByVariable x-ai-role: chatbot_crm_specialist x-ai-description: Enables targeted lookup of bot contacts by a specific variable value — useful for segmentation, personalization pipelines, and triggering flows based on contact attributes. Unlike a general contact list, this endpoint finds contacts who match a precise data condition (e.g., all contacts where `plan = 'pro'` or `city = 'Kyiv'`), making it essential for data-driven automation. x-ai-reasoning-instructions: - Either `variable_id` or `variable_name` must be provided alongside `variable_value` — clarify with the user if both are missing. - If `bot_id` is not provided, ask the user to specify which bot to search in, since variables are bot-scoped. - Use `size` and `skip` for paginated retrieval when the result set may be large; default page size is usually 10–25. - Variable names and values are case-sensitive — confirm exact casing with the user if no results are returned. - If the user wants to find contacts for a campaign segment, suggest chaining this with a messaging or tagging operation. x-ai-responding-instructions: - Report how many contacts were found matching the variable condition. - If the result is empty, suggest verifying the variable name/value spelling or checking if the variable exists for that bot. - If pagination was used, remind the user that more records may exist and suggest incrementing `skip`. - Highlight key contact identifiers (e.g., contact ID, name) from the result to help the user proceed. x-ai-suggestions: - Search by `variable_name=plan` and `variable_value=premium` to find premium subscribers. - Use `skip=0&size=50` for the first page of results. - Chain with a send-message endpoint to target the returned contacts directly. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/sendText: post: summary: Send a text message to a contact description: Sends a text message to 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. message_type: type: string enum: - MESSAGE_TAG - RESPONSE description: '' example: RESPONSE message_tag: $ref: '#/components/schemas/Campaign/properties/message_tag' text: type: string description: Message text to send, maximum characters -, may include emoji required: - contact_id - message_type - tag - text responses: '200': description: Operation successful content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' operationId: sendTextToContact x-ai-role: chatbot_communication_specialist x-ai-description: Sends a direct text message to a specific contact within a chatbot conversation. This is a real-time messaging action — the message is delivered immediately to the contact's chat window. The message_type field controls whether this is a free-form reply (RESPONSE, valid within the 24-hour messaging window) or a pre-approved template outside that window (MESSAGE_TAG). Choosing the wrong type will result in a policy violation or delivery failure. x-ai-reasoning-instructions: - Verify that contact_id is valid and belongs to an active contact — use contact search by tag or variable if needed. - 'Check message_type: use RESPONSE only if the contact has sent a message within the last 24 hours; otherwise use MESSAGE_TAG with an appropriate tag.' - If message_type is MESSAGE_TAG, ensure message_tag is provided and corresponds to an approved use case. - Validate that the text does not exceed the platform character limit and is properly encoded (emoji are supported). - Do not send sensitive data (passwords, tokens, PII) as plain text in the message body. x-ai-responding-instructions: - Confirm the message was sent successfully and mention the contact_id it was delivered to. - If message_type was MESSAGE_TAG, note which tag was used for auditing purposes. - If the request fails due to a 24-hour window constraint, suggest switching to MESSAGE_TAG with a suitable tag. - If contact_id is not found, recommend using the contact search endpoint to retrieve the correct ID. x-ai-suggestions: - Use RESPONSE type for replies within active conversation windows. - Use MESSAGE_TAG with 'POST_PURCHASE_UPDATE' for order-related follow-ups outside the 24h window. - Combine with contact search endpoints to dynamically resolve contact_id before sending. x-ai-capabilities: confirmation: type: Recommended message: You are about to send a message directly to a contact. Confirm the text content and recipient before proceeding. security_info: data_handling: - ExternalDelivery - UserFacing servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/send: post: summary: Send message to a contact description: Sends message to 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. message: properties: type: type: string enum: - UPDATE - RESPONSE - MESSAGE_TAG description: '' example: RESPONSE tag: type: string enum: - HUMAN_AGENT - CUSTOMER_FEEDBACK description: '' example: HUMAN_AGENT content_type: type: string enum: - message - media_img - media_file - template description: Type of data sent example: message text: type: string description: The parameter is required if the `content_type` parameter is equal to `message` example: Hello world! img: type: sting description: The parameter is required if the `content_type` parameter is equal to `media_img` example: https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png file: type: string description: The parameter is required if the `content_type` parameter is equal to `media_file` example: https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png data: type: object description: The paramater is required if the `content_type` paramater is equal to `template` properties: attachment: type: object properties: type: type: string enum: - template payload: type: object properties: template_type: type: string enum: - generic elements: type: array items: type: object properties: title: type: string subtitle: type: string image_url: type: string example: https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png buttons: type: array items: type: object properties: type: type: string enum: - web_url - postback title: type: string url: type: string type: object required: - type - content_type required: - contact_id - message examples: Send a text message: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: message text: Hello world! Send a message with a file: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: media_file file: https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png Send a message with an image: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: media_img img: https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png Send a message with a carousel: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: template data: attachment: type: template payload: template_type: generic elements: - title: Example title subtitle: Example subtitle image_url: https://example.com/image.png buttons: - type: web_url title: Example button url: https://example.com/ Send a message with url button: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: template data: attachment: type: template payload: template_type: generic elements: - title: Example title buttons: - type: web_url title: Example button url: https://example.com/ Send a message with payload button: value: contact_id: string message: type: RESPONSE tag: CUSTOMER_FEEDBACK content_type: template data: attachment: type: template payload: template_type: generic elements: - title: Example title buttons: - type: postback title: Example button data: chain: string responses: '200': description: Operation successful content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' operationId: sendContactMessage x-ai-role: chatbot_communication_specialist x-ai-description: Delivers a direct message to a specific chatbot contact identified by contact_id. This endpoint is the primary outbound channel for agent-initiated or automated communication — not just a message sender, but a dispatch mechanism that supports rich formats (text, media, carousel templates) and Facebook Messenger delivery rules (message type determines if the message can be sent outside the 24h window). Choosing the wrong `type` can result in policy violations on the platform side. x-ai-reasoning-instructions: - Always resolve `contact_id` before calling — it is not a human-readable identifier. Use contact search by tag or variable if only a name/email is known. - 'Match `type` to the business context: use `RESPONSE` for replies within the 24h window, `MESSAGE_TAG` with an appropriate `tag` for out-of-window messages, and `UPDATE` only for subscription-based updates.' - 'Validate that `content_type` and its corresponding payload field are consistent: if `content_type` is `message`, `text` must be present; `media_img` requires `img`; `media_file` requires `file`; `template` requires `data.attachment`.' - For `template` messages, ensure `elements` array is non-empty and each element has at least a `title`. - Avoid using `HUMAN_AGENT` tag unless a live agent is actually taking over the conversation — misuse may violate platform policies. x-ai-responding-instructions: - Confirm that the message was dispatched successfully without repeating raw response fields. - If the message type was `MESSAGE_TAG`, mention which tag was used and why it was appropriate. - If an error occurs, identify whether the cause is an invalid `contact_id`, an incompatible `type`/`content_type` combination, or a platform-side policy rejection, and suggest a concrete fix. - After a successful send, suggest checking contact activity or setting up a follow-up flow as next steps. x-ai-suggestions: - Use type=RESPONSE for standard replies within the active conversation window. - Use type=MESSAGE_TAG with tag=HUMAN_AGENT when a human agent is intervening. - Use content_type=template with generic carousel for rich product or menu presentations. - Retrieve contact_id via the contact search endpoint before calling this operation. x-ai-capabilities: confirmation: type: recommended message: You are about to send a message directly to a contact. Confirm the content and contact before dispatching. security_info: data_handling: - ExternalMessageDispatch - ContactInteraction servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/sendTyping: post: summary: Send typing indicator description: Initiate typing indicator for the specified contact. security: - oAuth2ClientCredentials: [] tags: - Contacts requestBody: description: '' required: true content: application/json: schema: type: object required: - contact_id properties: contact_id: type: string description: The unique identifier of the contact to whom the typing indicator will be sent. example: contact_id: string responses: '200': description: Indicates whether the typing indicator was successfully sent. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' operationId: sendTypingIndicator x-ai-role: chatbot_engagement_specialist x-ai-description: Triggers a transient 'typing...' signal in the contact's chat interface before the actual message is sent. This simulates human-like interaction latency, reducing perceived automation and increasing conversational trust. Particularly effective in chatbot scenarios where an immediate bot reply feels unnatural — injecting a short typing indicator before a response significantly improves UX and open/reply rates. x-ai-reasoning-instructions: - Always send the typing indicator immediately before dispatching the actual message, not as a standalone UX gesture. - Verify the contact_id is valid and the contact is reachable before triggering the indicator to avoid silent failures. - Consider the messaging channel context — typing indicators may behave differently or not be supported across all chatbot integrations. - Do not send the indicator repeatedly in a loop; one invocation per conversational turn is sufficient. x-ai-responding-instructions: - Confirm that the typing indicator was successfully dispatched and clarify that it is a transient signal, not a message. - Suggest following up immediately with the actual message send operation to complete the interaction flow. - If the call fails, check whether the contact_id is correct and whether the contact's channel supports typing indicators. x-ai-suggestions: - Use this before `sendMessage` to create a natural conversation rhythm. - Combine with a short delay (1–3 seconds) before sending the actual message for a more human-like experience. x-ai-capabilities: confirmation: type: None security_info: data_handling: - TransientSignal servers: - description: '' url: https://api.sendpulse.com/messenger /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: crm_data_specialist x-ai-description: This endpoint writes or overwrites a structured data field on a specific contact profile. In SendPulse chatbots, variables are the primary mechanism for personalizing flows, segmenting audiences, and storing transactional state (e.g., order ID, last product viewed, subscription tier). Setting a variable at the right moment in a conversation or automation flow is what turns a generic chatbot into a context-aware assistant. x-ai-reasoning-instructions: - Confirm the contact_id is valid before calling — use a contact search by tag or variable if uncertain. - Prefer variable_id over variable_name when available to avoid ambiguity from name collisions or renames. - Variables can hold string, number, or boolean values — match the type to what downstream flows or conditions expect. - Batch multiple variable assignments in a single request rather than making sequential calls to minimize latency. - If overwriting a sensitive variable (e.g., subscription status, payment flag), verify intent — this is a destructive update with no built-in undo. x-ai-responding-instructions: - Confirm which contact and which variables were updated. - If the operation succeeds, suggest verifying the value via a contact lookup or triggering a flow that depends on the variable. - If the contact_id is unknown, guide the user toward the contact search endpoints first. - Highlight the distinction between variable_name and variable_id approaches so the user understands the trade-offs. x-ai-suggestions: - Set onboarding_step to 'completed' after a user finishes a bot flow - Store an order_id returned from an external webhook into a contact variable for follow-up flows - Update subscription_tier when a payment event is received x-ai-capabilities: confirmation: type: Recommended message: This will overwrite the current value of the specified variable(s) for the contact. Confirm before proceeding if the variable drives active automation flows. security_info: data_handling: - ContactDataWrite - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_hygiene_specialist x-ai-description: 'Clears the value of a specific variable for a given contact, effectively removing that data point from their profile. Use this when a contact''s attribute becomes invalid, outdated, or needs to be reset — for example, after a subscription tier change or data correction request. This is a destructive operation on contact-level metadata: the variable definition itself remains intact, only the contact''s value is removed.' x-ai-reasoning-instructions: - Ensure you have a valid contact_id before proceeding — it can be retrieved via contact search by tag or variable. - You must supply either variable_id or variable_name, but not necessarily both; prefer variable_id if available for precision. - Do not confuse this endpoint with deleting the variable definition itself — this only removes the value for a specific contact. - If the goal is to update a variable value rather than remove it, use the appropriate update endpoint instead. - Confirm that the variable actually has a value set for this contact before calling, to avoid unnecessary API calls. x-ai-responding-instructions: - Confirm that the variable value was successfully removed from the specified contact. - Distinguish clearly between 'variable value deleted' and 'variable deleted' to avoid confusion. - If the contact or variable is not found, explain how to retrieve valid IDs using contact search or variable listing methods. - Suggest verifying the contact's current variable state after deletion if data consistency is critical. x-ai-suggestions: - Use contact search by tag to obtain contact_id before calling this endpoint. - After deletion, call the contact detail endpoint to confirm the variable is cleared. - If resetting multiple contacts, consider batching calls and monitoring for rate limits. x-ai-capabilities: confirmation: type: Recommended message: This will permanently remove the variable value for the specified contact. Confirm before proceeding. security_info: data_handling: - DestructiveWrite - ContactDataModification servers: - description: '' url: https://api.sendpulse.com/messenger /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. This is a housekeeping operation that signals all messages in the conversation have been reviewed — typically triggered after a support agent opens and reads a contact's message thread, keeping the inbox state accurate across team members. x-ai-reasoning-instructions: - Verify that the contact_id exists before calling to avoid silent no-ops. - Use this after fetching or displaying contact messages — not as a standalone action. - If the unread count is already 0, the call is still safe but redundant; inform the user if appropriate. x-ai-responding-instructions: - Confirm success by referencing the returned `count` — the number of messages marked as read. - If count is 0, note that no unread messages were found for this contact. - Suggest fetching the updated contact record to reflect the new unread state in the UI. x-ai-suggestions: - Call after displaying a contact's message history to auto-clear unread state. - Chain with `getContactMessages` to show messages and mark them read in one workflow. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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: markContactUnread x-ai-role: customer_support_specialist x-ai-description: Marks the last message of a contact as unread, effectively flagging the chat for follow-up. This is a workflow management action — it signals to the support team that a conversation requires attention without sending any message. Useful for triaging incoming chats or restoring visibility to conversations that were prematurely dismissed. x-ai-reasoning-instructions: - Confirm that the contact_id is valid and corresponds to an existing contact before calling. - Clarify with the user whether they want to flag this contact for follow-up or simply restore unread state — this helps avoid accidental misuse. - Note that only the *last* message is marked unread, not the entire conversation history. x-ai-responding-instructions: - 'Confirm the action by reporting the returned `count` value (expected: 1).' - If count is 0, inform the user that no messages were affected — the contact may have no messages or the chat was already in an unread state. - Suggest assigning the contact to an agent or adding a note as a logical next step. x-ai-suggestions: - Use after reviewing a message to restore it as a reminder to respond later. - Combine with contact filtering to batch-flag unanswered chats for a support shift handoff. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/setTag: post: summary: Assign a tag to a 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_segmentation_specialist x-ai-description: Tags are the primary segmentation mechanism for contacts in SendPulse CRM and chatbot flows. Assigning tags enables conditional branching in automation flows, targeted broadcast filtering, and behavioral segmentation. Unlike variables (which store values), tags act as boolean labels — their mere presence on a contact carries semantic meaning used in flow conditions and audience targeting. x-ai-reasoning-instructions: - Resolve the contact_id before calling — it is not human-readable; use search-by-tag or search-by-variable endpoints if only a name or phone is known. - Tags are case-sensitive in SendPulse; confirm the exact casing of existing tags before assigning to avoid duplicates like 'VIP' vs 'vip'. - Multiple tags can be assigned in a single call — batch them instead of making repeated single-tag calls to reduce API usage. - Verify that the tags being assigned are meaningful within the active automation flows; assigning an unexpected tag may trigger unintended flow branches. x-ai-responding-instructions: - Confirm which tags were successfully assigned to which contact. - If the contact is part of active automation flows, warn the user that the new tags may immediately trigger flow conditions. - Suggest using a contact lookup endpoint first if the user is unsure of the contact_id. x-ai-suggestions: - vip_customer - onboarding_complete - interested_in_pro_plan - support_escalated x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_manager x-ai-description: Removes a specific tag from a contact's profile in the CRM. Tags are used for segmentation, automation triggers, and filtering — removing one affects which flows, campaigns, or filters the contact will match going forward. x-ai-reasoning-instructions: - Before removing, confirm with the user which contact and tag are targeted — contact_id is not human-readable, so resolve it via search if needed. - Warn that removing a tag may exclude the contact from active automations or segments that rely on it. - If the tag does not exist on the contact, the API may still return success — clarify this is idempotent if confirmed. x-ai-responding-instructions: - Confirm the tag was successfully removed and mention both the contact ID and the tag name in the response summary. - If the contact participates in any automations triggered by this tag, suggest reviewing those flows. - Suggest using a contact search or listing tags to verify the updated state. x-ai-capabilities: confirmation: type: Recommended message: This will permanently remove the tag from the contact. Automations or segments depending on this tag may be affected. security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_lifecycle_manager x-ai-description: Suppresses a specific contact from receiving any future campaigns or autoflow messages. This is a soft deactivation — the contact record is preserved in the audience, but excluded from all outgoing communication. Useful for honoring opt-out requests, pausing contacts during sensitive periods, or managing compliance without data deletion. x-ai-reasoning-instructions: - Verify the contact_id exists before attempting to disable — an invalid ID will result in an error. - Distinguish between disabling (reversible suppression) and deleting (permanent removal) — prefer disabling when the user wants to pause communication, not erase data. - If the user provides an email or phone instead of a contact_id, remind them to first use a contact search endpoint to retrieve the correct ID. - Consider whether the intent is GDPR/unsubscribe compliance — in that case, advise logging the action externally as well. x-ai-responding-instructions: - Confirm that the contact has been successfully disabled and will no longer receive campaigns or autoflows. - Clarify that the contact record still exists and can be re-enabled if needed. - If the contact was already disabled, communicate that gracefully without implying an error. - Suggest using the contact search endpoint if the user is unsure about the correct contact_id. x-ai-suggestions: - Use contact search by tag or variable to obtain the contact_id before calling this endpoint. - To reverse this action, use the enable contact 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 campaigns or autoflows. Confirm before proceeding. security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /contacts/enable: post: summary: Enable contact description: Enables a contact in your audience list. Campaigns and autoflows resume 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: crm_contact_lifecycle_manager x-ai-description: Reactivates a previously disabled contact, restoring their participation in all active campaigns and autoflows. This is the recovery operation after a contact was suppressed — whether manually or due to a bounce/unsubscribe event. Enabling a contact resumes the full marketing lifecycle for that individual. x-ai-reasoning-instructions: - Before enabling, confirm the contact is currently in a disabled state — enabling an already-active contact is a no-op but may indicate a misunderstanding. - Clarify with the user why the contact was disabled originally (manual action, unsubscribe, bounce) — re-enabling a hard-bounce address may damage sender reputation. - Ensure the contact_id is valid; it can be retrieved via contact search by tag or variable, or from the chat window URL in the SendPulse dashboard. - Consider whether re-enabling aligns with GDPR/CAN-SPAM consent requirements for the contact. x-ai-responding-instructions: - Confirm the contact has been successfully re-enabled and that campaigns/autoflows will resume. - Remind the user that any autoflow steps the contact missed while disabled will not be retroactively triggered. - If the contact was disabled due to a complaint or hard bounce, warn the user about potential deliverability risks. x-ai-suggestions: - Use `searchContactsByTag` or `searchContactsByVariable` to retrieve the contact_id before calling this endpoint. - After enabling, verify contact status with a contact lookup operation. - Pair with `disableContact` to build a contact suppression/reactivation workflow. x-ai-capabilities: confirmation: type: Recommended message: Re-enabling this contact will resume all campaigns and autoflows targeting them. Confirm this is intentional, especially if the contact was suppressed due to a complaint or bounce. security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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 an irreversible audience reduction action — the contact loses all history and can only return by re-subscribing through the bot. Use with caution in cleanup workflows or GDPR compliance flows. x-ai-reasoning-instructions: - Confirm the contact_id is correct before proceeding — deletion cannot be undone via API. - Remind the user that the contact can only be re-added if they voluntarily subscribe to the bot again. - If the goal is to unsubscribe (not delete), verify whether a softer action (e.g., pause or tag) is more appropriate. - In GDPR or data erasure contexts, confirm this endpoint satisfies the right-to-erasure requirement for chatbot data. x-ai-responding-instructions: - Confirm the contact was successfully deleted and is no longer in the audience. - Warn that re-adding the contact requires their active re-subscription to the bot. - If an error occurs, clarify whether the contact_id was invalid or the contact was already removed. x-ai-suggestions: - Retrieve contact_id first using contact search by tag or variable. - Use this endpoint in GDPR data-erasure flows to fully remove a user. - Consider exporting contact data before deletion if historical data is needed. x-ai-capabilities: confirmation: type: Required message: This will permanently remove the contact from the audience. They can only return by re-subscribing to the bot. security_info: data_handling: - ResourceDestruction - IrreversibleAction servers: - description: '' url: https://api.sendpulse.com/messenger /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: marketing_automation_specialist x-ai-description: Retrieves the remaining duration of a manually triggered automation pause for a specific contact. In SendPulse, operators can temporarily halt autoflows for individual contacts (e.g., during active support sessions or sensitive periods). This endpoint exposes how much time is left before autoflows resume, enabling agents to decide whether to wait, override, or act accordingly. x-ai-reasoning-instructions: - Ensure the contact_id is valid before calling — use contact search by tag or variable if the ID is not already known. - A response indicating zero or no remaining time means autoflows are currently active for this contact. - Use this endpoint before triggering any manual intervention to understand whether automation is already paused. - If the pause was set by a human operator, coordinate with them before resuming flows programmatically. x-ai-responding-instructions: - State clearly how much time remains in the pause in a human-readable format (e.g., '2 hours and 15 minutes remaining'). - If the pause has expired or was never set, clarify that autoflows are currently active for this contact. - 'Suggest next steps: either wait for the pause to expire, extend the pause, or proceed with automation-aware actions.' x-ai-suggestions: - Check this before sending a manual message to avoid conflicting with scheduled autoflows. - Use alongside `setPauseAutomation` to manage the pause lifecycle for a contact. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - description: '' url: https://api.sendpulse.com/messenger /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: setContactPauseAutomation x-ai-role: crm_automation_specialist x-ai-description: Temporarily suspends all active autoflows for a specific contact for a defined number of minutes. This is a critical operational control used when a contact needs a 'cool-down' period — for example, after a support ticket is opened, a manual sales call is scheduled, or when preventing message fatigue during sensitive periods. Unlike unsubscribing, this is a reversible, time-bound pause that preserves the contact's position in the automation pipeline. x-ai-reasoning-instructions: - Verify the contact_id is valid before calling — use a contact search endpoint if only an email or tag is known. - 'Confirm the intent: pausing autoflows is time-bound and reversible; if the user wants to permanently stop messaging, suggest unsubscribing instead.' - Validate that `minutes` is a positive integer and represents a reasonable window (e.g., 60–10080 for 1 hour to 1 week); warn if an unusually large value is provided. - Consider whether other contacts in the same segment also need pausing — this endpoint operates on a single contact at a time. - Check if the contact is currently in an active autoflow before pausing; pausing a contact with no active flows still succeeds but has no immediate effect. x-ai-responding-instructions: - Confirm the pause was applied and state clearly when it will expire (current time + minutes). - If the user seems to want a permanent stop, clarify the difference between pausing and unsubscribing. - Suggest resuming automation manually earlier if needed, and explain how to do so. - If the operation fails, check whether the contact_id is correct and the contact exists in the account. x-ai-suggestions: - Use 60 minutes for a short cool-down after a support interaction. - Use 1440 minutes (24 hours) to pause during a manual outreach day. - Use 10080 minutes (7 days) for a full weekly suppression window. x-ai-capabilities: confirmation: type: Recommended message: This will pause all active autoflows for the contact for {minutes} minutes. Confirm? security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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: crm_automation_specialist x-ai-description: Removes the pause flag from a contact's automation queue, restoring their eligibility to receive autoflow messages. This is the counterpart to pausing automation — used when a contact was temporarily excluded (e.g., during support resolution, campaign hold, or manual intervention) and is now ready to re-enter automated sequences from where they left off or from the beginning. x-ai-reasoning-instructions: - Verify the contact_id is valid before calling — an invalid ID will silently fail or return an error. - Check whether the contact was actually paused before resuming; resuming an already-active contact is a no-op but worth confirming to the user. - Consider whether resuming will re-trigger the full autoflow from step 1 or continue from the paused step — clarify this business behavior with the user if relevant. - If the user wants to resume multiple contacts, note that this endpoint handles one contact at a time — suggest looping or batching logic accordingly. x-ai-responding-instructions: - Confirm that the pause has been removed and the contact will now receive autoflow messages again. - Mention the contact_id that was affected to give the user clear confirmation. - Suggest verifying the contact's current autoflow status if the user wants to confirm the change took effect. - If the operation fails, help the user validate the contact_id source (search by tag, variable, or chat window URL). x-ai-suggestions: - Use `searchContactsByTag` or `searchContactsByVariable` to retrieve the contact_id if not known. - After resuming, monitor autoflow engagement metrics to ensure the contact is processing messages as expected. - If managing bulk resume operations, consider iterating over a contact list and calling this endpoint per contact. x-ai-capabilities: confirmation: type: Recommended message: This will resume all paused autoflows for the specified contact. Confirm before proceeding if the contact was paused intentionally (e.g., active support case). security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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 all operator-written notes attached to a specific chatbot contact. Notes are internal annotations left by support agents — they capture context about the contact's history, preferences, or issues that is not visible to the contact itself. This endpoint is essential for building a full picture of a contact before engaging them or escalating support cases. x-ai-reasoning-instructions: - Ensure both `bot_id` and `contact_id` are provided — both are required; missing either will cause the request to fail. - If `contact_id` is unknown, first resolve it via the contact search by tag or variable endpoint before calling this. - Notes are operator-internal; do not surface their raw content to end users unless explicitly instructed. - If the returned list is empty, it does not mean the contact is new — operators may simply not have added notes yet. x-ai-responding-instructions: - Present notes in chronological order if timestamps are available, highlighting the most recent one. - Summarize key themes across notes if there are multiple (e.g., 'recurring billing issue', 'VIP customer'). - If no notes exist, suggest that the operator add a note to improve future support context. - Do not expose raw internal note content to the end contact — treat this as agent-only information. x-ai-suggestions: - Use this before initiating an outbound message to a contact to understand prior context. - Combine with contact variable data for a complete contact profile. - After reading notes, consider using the 'add note' endpoint to append updated observations. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly - InternalOperatorData servers: - description: '' url: https://api.sendpulse.com/messenger /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 specific contact's profile within a bot context. Notes are not visible to the contact — they serve as a CRM-style annotation layer for support teams to log observations, agreements, or follow-up instructions. Essential for async team collaboration on shared contact queues. x-ai-reasoning-instructions: - Ensure the contact_id belongs to the same bot identified by bot_id — cross-bot note creation will fail. - Notes are internal and never surfaced to the contact; clarify this if the user seems to intend sending a message instead. - If the user provides a contact name rather than an ID, remind them to first resolve the ID via the contact search endpoint. - Keep note text concise and actionable — verbose free-text notes reduce team usability. x-ai-responding-instructions: - Confirm the note was successfully attached to the contact. - If the operation fails due to an invalid contact_id or bot_id, suggest verifying IDs using the contacts search or bots list endpoints. - Distinguish clearly between 'operator note' (internal) and 'message to contact' (external) if there's any ambiguity in the user's request. x-ai-suggestions: - Agreed to refund — follow up after 48h - VIP customer, escalate immediately if unresolved - Waiting for user to confirm shipping address x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_contact_manager x-ai-description: Updates an existing operator note attached to a specific contact in a chatbot conversation. Notes are internal annotations visible only to the team — they capture context, history, or flags about a contact that help operators provide personalized support without relying on memory or external tools. x-ai-reasoning-instructions: - Before updating, confirm that both contact_id and bot_id belong to the same conversation context — mismatched IDs will silently fail or update the wrong record. - Verify that note_id is valid and belongs to the specified contact; fetching existing notes beforehand is advised. - If the new text is empty or identical to the existing note, warn the user that the update may be unnecessary. - Note updates overwrite the previous text entirely — partial edits are not supported, so retrieve and preserve any content the user wants to keep. x-ai-responding-instructions: - Confirm that the note was successfully updated and reference the note_id for traceability. - If the operation fails due to a missing or invalid note_id, suggest fetching the contact's notes list first. - Avoid exposing raw IDs in the response summary — present them as references the user can use for follow-up actions. x-ai-suggestions: - Followed up on pricing inquiry — awaiting response. - VIP customer — escalate all issues to senior support. - Requested callback on 2026-04-01 at 10:00 UTC. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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' servers: - description: '' url: https://api.sendpulse.com/messenger /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_manager x-ai-description: Assigns a specific operator as the responsible agent for a chat contact. This is a routing action that determines who is accountable for following up with the contact. Proper assignment ensures no chat falls through the cracks and enables SLA tracking per operator. x-ai-reasoning-instructions: - Before assigning, verify the contact_id is valid by searching the contact first if it was not recently retrieved. - Confirm the operator_id exists and is an active user — IDs can be found at https://login.sendpulse.com/settings/#users. - Check whether the contact already has an assigned operator to avoid redundant reassignment. - If assigning as part of a routing workflow, consider whether the operator's current load is appropriate. x-ai-responding-instructions: - Confirm the assignment by mentioning both the contact and the operator involved. - 'If `data` is null or false despite `success: true`, note this as an edge case and suggest verifying the assignment via a contact lookup.' - If the operation fails, suggest verifying that both IDs are correct and that the OAuth2 token has sufficient scope. x-ai-suggestions: - Use `searchContactsByTag` or `searchContactsByVariable` to obtain a valid `contact_id` before calling this endpoint. - Retrieve available operator IDs from the SendPulse account settings at https://login.sendpulse.com/settings/#users. x-ai-capabilities: confirmation: type: Recommended message: You are about to reassign responsibility for a contact's chat to a specific operator. Confirm before proceeding. security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_operations_specialist x-ai-description: Releases the operator assignment for a specific chat contact, effectively making the conversation unowned. This is a critical workflow step in queue management — used when reassigning chats, during agent shift changes, or when escalating to a different team. Unassigning without a follow-up reassignment routes the contact back to the general queue. x-ai-reasoning-instructions: - Confirm the contact_id is valid and the contact exists before attempting the operation. - Check whether the contact currently has an assigned operator — unassigning an already-unassigned contact may be a no-op or indicate a logic error upstream. - If the intent is to reassign (not simply unassign), suggest chaining this call with the assign operator endpoint immediately after. - 'Be cautious in automated flows: unassigning an active conversation mid-session may disrupt ongoing customer interactions.' x-ai-responding-instructions: - Confirm that the operator was successfully unassigned by referencing the contact_id. - 'If `data: false` is returned despite `success: true`, flag this as an ambiguous state and suggest verifying the contact''s current assignment.' - 'Suggest a logical next step: either reassign the contact to another operator or leave it for queue-based routing.' - If the operation fails, advise checking whether the contact_id is correct and whether the OAuth2 token has sufficient CRM permissions. x-ai-suggestions: - After unassigning, use the assign operator endpoint to route the contact to a specific agent. - Use this endpoint as part of a shift-handoff automation to clear assignments at the end of a work period. - Combine with contact search by tag to bulk-unassign contacts from a departing operator. x-ai-capabilities: confirmation: type: Recommended message: This will remove the currently assigned operator from the contact's chat. The conversation will become unassigned. Proceed? security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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, effectively escalating its priority in the inbox queue. Use this when a contact requires immediate attention or when a conversation needs to be surfaced from a low-priority or resolved state. This is a lightweight state-change operation — it does not send a message. x-ai-reasoning-instructions: - Ensure the contact_id is valid before calling — use a contact search by tag or variable if the ID is unknown. - Understand that 'opening' a chat is a priority signal, not a message dispatch — do not confuse it with initiating a conversation. - If the goal is to re-engage a contact, consider whether sending a message would be more appropriate than simply marking the chat as open. - Check if the chat is already in an open state to avoid redundant calls. x-ai-responding-instructions: - Confirm the chat has been marked as open and explain that its priority has been increased in the queue. - If the user's goal is to follow up with the contact, suggest sending a message via the appropriate messaging endpoint. - If the contact_id was not found, guide the user to retrieve it via contact search or from the account UI (address bar of the chat window). x-ai-suggestions: - After opening the chat, use the send-message endpoint to proactively reach out to the contact. - Use contact search by tag or variable to resolve the contact_id before calling this endpoint. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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: Terminates an active chat session with a contact and reduces its queue priority. Use this when a conversation is resolved or no longer requires agent attention. Closing a chat is a deliberate state transition — it signals that the interaction is complete and deprioritizes the contact in the support queue, affecting routing and visibility in the operator interface. x-ai-reasoning-instructions: - Confirm the contact_id is valid before sending — use a contact search by tag or variable if the ID is not already known. - Verify the chat is currently open; closing an already-closed chat may return an error or be a no-op. - Consider whether the contact should receive a closing message before this call is made — this endpoint does not send notifications. - If the user intends to close multiple chats, process them sequentially to avoid race conditions. x-ai-responding-instructions: - Confirm that the chat has been successfully closed and mention the contact_id for traceability. - Clarify that closing the chat lowers the contact's priority in the queue — this affects how soon they appear to operators. - If the operation fails, check whether the contact_id is correct or whether the chat was already closed. - Suggest reopening the chat via a new inbound message or a dedicated reopen endpoint if the user needs to resume the conversation. x-ai-capabilities: confirmation: type: Recommended message: This will close the active chat for the contact and lower their queue priority. Proceed? security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/messenger /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_2' operationId: setContactName x-ai-role: crm_data_steward x-ai-description: Updates the human-readable display name of a contact record in SendPulse CRM. This is a targeted mutation — it affects only the name field without touching other contact attributes. Useful for correcting misspellings, applying naming conventions, or syncing display names after an external CRM import. x-ai-reasoning-instructions: - Ensure you have the correct contact_id before calling — retrieve it via contact search if uncertain, as the ID is not guessable. - Confirm the new name is non-empty and properly formatted (e.g., 'First Last') to avoid storing a blank or malformed display name. - If the user provides only a first name or only a last name, ask whether they intend to store a partial name or need the full name. x-ai-responding-instructions: - Confirm the update by echoing back the contact_id and the new name that was set. - If the operation fails, clarify whether the contact_id was invalid or the account lacks permission. - Suggest verifying the change via a contact lookup if the user wants to confirm the update took effect. x-ai-suggestions: - Use the contact search endpoint to resolve a contact_id from an email or phone before calling this. - After renaming, consider updating other contact fields (e.g., phone, variables) if the name change reflects a broader profile correction. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/live-chat /sms/numbers: post: summary: Add phone numbers to a mailing list operationId: addSmsNumbers tags: - Contacts x-ai-role: sms_marketing_specialist x-ai-description: 'Imports a batch of phone numbers into a designated address book. This is the baseline operation for building a mobile audience. ' x-ai-reasoning-instructions: - Verify the `addressBookId` exists before attempting the import. - Ensure phone numbers are in international E.164 format (e.g., 380...). x-ai-responding-instructions: - Report the total number of successfully added contacts. - Note if any numbers were skipped due to existing in the list. x-ai-suggestions: - Use `addSmsNumbersWithVariables` if you have metadata like names or dates. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - addressBookId - phones properties: addressBookId: type: integer phones: type: array items: type: string responses: '200': description: Import result content: application/json: schema: type: object properties: result: type: boolean counters: type: object properties: added: type: integer exceptions: type: integer exists: type: integer '401': description: Unauthorized '403': description: Forbidden put: summary: Update variables for multiple phone numbers operationId: updateSmsVariablesBatch tags: - Contacts x-ai-role: sms_marketing_specialist x-ai-description: 'Batch updates variable values for a set of phone numbers. Critical for keeping contact data like ''Last Purchase'' or ''Loyalty Points'' synchronized. ' x-ai-reasoning-instructions: - Validate that the `variables` array contains correctly structured objects (name, type, value). x-ai-responding-instructions: - Confirm the number of contacts updated. x-ai-suggestions: - Use this to refresh campaign-specific variables before a blast. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - addressBookId - phones - variables properties: addressBookId: type: integer phones: type: array items: type: string variables: type: array items: type: object required: - name - type - value properties: name: type: string type: type: string enum: - string - number - date value: oneOf: - type: string - type: number responses: '200': description: Update result content: application/json: schema: type: array items: type: object properties: result: type: boolean counters: type: object properties: updated: type: integer '401': description: Unauthorized '403': description: Forbidden delete: summary: Remove phone numbers from a mailing list operationId: removeSmsNumbers tags: - Contacts x-ai-role: compliance_officer x-ai-description: 'Surgically removes specific mobile contacts from an address book. Unlike the blacklist, this does not prevent future re-subscription. ' x-ai-reasoning-instructions: - Confirm the exact `addressBookId` to avoid cross-list deletions. x-ai-responding-instructions: - State clearly how many numbers were removed. x-ai-suggestions: - Use this for list hygiene (e.g., removing unengaged users). x-ai-capabilities: confirmation: type: Required security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - addressBookId - phones properties: addressBookId: type: integer phones: type: array items: type: string responses: '200': description: Deletion result content: application/json: schema: type: object properties: result: type: boolean counters: type: object properties: deleted: type: integer '401': description: Unauthorized '403': description: Forbidden servers: - url: https://api.sendpulse.com /sms/numbers/variables: post: summary: Add phone numbers with complex variables operationId: addSmsNumbersWithVariables tags: - Contacts x-ai-role: sms_marketing_specialist x-ai-description: 'Advanced contact ingestion endpoint that maps specific variables to each phone number in a single payload. Ideal for personalized onboarding. ' x-ai-reasoning-instructions: - Note that `date` variable format must be `YYYY-MM-DD` (no time). x-ai-responding-instructions: - Confirm successful ingestion and variable mapping. x-ai-suggestions: - Structure your CRM export to match this schema for seamless sync. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - addressBookId - phones properties: addressBookId: type: integer phones: type: object additionalProperties: type: array items: type: array items: type: object required: - name - type - value properties: name: type: string type: type: string value: type: string responses: '200': description: Batch result content: application/json: schema: type: array items: type: object properties: result: type: boolean counters: type: object '401': description: Unauthorized '403': description: Forbidden servers: - url: https://api.sendpulse.com /addressbooks/{id}/phone: parameters: - name: id in: path required: true schema: type: integer put: summary: Change a phone number for a contact operationId: updateContactPhone tags: - Contacts parameters: [] x-ai-role: customer_engagement_specialist x-ai-description: 'Maps an SMS identity to an existing email-based contact record. Enables multi-channel communication (Email + SMS) for a single user entity. ' x-ai-reasoning-instructions: - Check if the contact exists by email first. x-ai-responding-instructions: - Confirm the user is now reachable via both Email and SMS. x-ai-suggestions: - Check if the phone number is already associated with another email to prevent duplication. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - email - phone properties: email: type: string phone: type: string responses: '200': description: Successfully updated content: application/json: schema: type: object properties: result: type: boolean '401': description: Unauthorized '403': description: Forbidden servers: - url: https://api.sendpulse.com /addressbooks/{id}/phones/variable: parameters: - name: id in: path required: true schema: type: integer post: summary: Change variables for a single phone contact operationId: updateSmsVariablesSingle tags: - Contacts parameters: [] x-ai-role: customer_engagement_specialist x-ai-description: 'Targeted update of metadata for a specific SMS contact within a list. Useful for real-time updates (e.g., updating ''Last Visited'' after a store visit). ' x-ai-reasoning-instructions: - Strictly follow the `YYYY-MM-DD` format for date variables. x-ai-responding-instructions: - Confirm the variables have been updated for the contact. x-ai-suggestions: - Ensure the `id` corresponds to the correct address book. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - phone - variables properties: phone: type: string variables: type: array items: type: object required: - name - value properties: name: type: string value: oneOf: - type: string - type: number responses: '200': description: Successful response content: application/json: schema: type: object properties: result: type: boolean '401': description: Unauthorized '403': description: Forbidden servers: - url: https://api.sendpulse.com /sms/numbers/info/{addressBookId}/{phoneNumber}: parameters: - name: addressBookId in: path required: true schema: type: integer - name: phoneNumber in: path required: true schema: type: string get: summary: Get information for a specific phone number operationId: getSmsNumberInfo tags: - Contacts parameters: [] x-ai-role: customer_engagement_specialist x-ai-description: 'Retrieves the profile of a mobile contact, including their current variable values and the date they were added to the list. ' x-ai-reasoning-instructions: - Verify the status (e.g., 1 for active). x-ai-responding-instructions: - Summarize the contact's current metadata. x-ai-suggestions: - If status is inactive, investigate if the user was blacklisted. x-ai-capabilities: confirmation: type: None responses: '200': description: Contact profile content: application/json: schema: type: array items: type: object properties: result: type: boolean data: type: object '401': description: Unauthorized '403': description: Forbidden servers: - url: https://api.sendpulse.com /contacts/getByTelegramId: get: summary: Get contact by Telegram ID description: Returns a bot contact by Telegram ID. security: - oAuth2ClientCredentials: [] tags: - Contacts parameters: - in: query name: bot_id required: true schema: type: string description: Bot identifier - in: query name: telegram_id required: true schema: type: integer description: Telegram ID of the user or chat - in: query name: business_connection_id required: false schema: type: - string - 'null' description: Telegram business connection identifier (optional) responses: '200': description: Contact successfully found content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/Contact_5' operationId: getContactByTelegramId x-ai-role: telegram_bot_integration_specialist x-ai-description: Retrieves a specific bot contact by their Telegram ID. This is the primary lookup mechanism when you know the user's Telegram identity but not the internal SendPulse contact ID — common in webhook handlers after receiving a Telegram update, or when syncing external CRM data with bot subscriber records. x-ai-reasoning-instructions: - Ensure bot_id belongs to an active Telegram bot in the account before querying. - telegram_id refers to Telegram's internal user/chat identifier — it is not a username or phone number. - If business_connection_id is provided, the lookup scope narrows to that specific business connection; omit it for standard bot contacts. - If the contact is not found (non-200 or empty data), consider whether the user has ever interacted with the bot — contacts are created only after the first interaction. x-ai-responding-instructions: - Confirm which bot the contact was found in by echoing the bot_id context. - If the contact is found, highlight key identifiable fields (e.g., name, telegram_id) from the returned Contact object. - If no contact is returned, explain that the user may not have started the bot yet or the telegram_id may be incorrect. - Suggest follow-up actions such as sending a message or updating contact variables. x-ai-suggestions: - Use this endpoint in Telegram webhook handlers to resolve incoming user messages to SendPulse contacts. - Combine with sendMessage endpoints to immediately act on the retrieved contact. - Pass business_connection_id only when operating in Telegram Business mode. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ReadOnly servers: - description: '' url: https://api.sendpulse.com/telegram /contacts/react: post: summary: React to a message description: Send a reaction (e.g. an emoji) to a specific message of a contact. security: - oAuth2ClientCredentials: [] tags: - Contacts requestBody: required: true description: Payload containing contact ID, message ID, and reaction details. content: application/json: schema: type: object required: - contact_id - message_id - reaction properties: contact_id: type: string description: The ID of the contact. message_id: type: string description: The ID of the message to react to. reaction: type: object description: Object with reaction details. required: - type - emoji properties: type: type: string enum: - emoji description: Type of reaction (for example, "emoji"). emoji: type: string description: The emoji character to use as reaction. example: contact_id: string message_id: string reaction: type: emoji emoji: ❤ responses: '200': description: Indicates the reaction was successfully recorded. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' operationId: reactToMessage x-ai-role: conversational_engagement_specialist x-ai-description: Sends an emoji reaction to a specific message in a contact's conversation thread. Reactions are lightweight engagement signals — they don't create a new message but attach sentiment metadata to an existing one. Use this to simulate or automate human-like acknowledgment of contact messages, which can improve perceived responsiveness in chatbot flows. x-ai-reasoning-instructions: - Ensure the contact_id corresponds to an active contact before sending a reaction. - Verify that the message_id belongs to the conversation of the specified contact — cross-contact message references will fail. - Currently only 'emoji' type is supported; validate the type field before constructing the payload. - Choose semantically appropriate emojis — a ❤ or 👍 signals positive acknowledgment, while ❓ may imply confusion. - Reactions are typically one-time per message per sender; avoid duplicate reactions on the same message. x-ai-responding-instructions: - Confirm that the reaction was recorded successfully, mentioning the emoji used. - If the operation fails, check whether the message_id is valid and belongs to the given contact. - Suggest follow-up actions such as sending a reply message or updating the contact's tag based on engagement. x-ai-suggestions: - Use ❤ to acknowledge a positive message from the contact. - Use 👍 to confirm receipt of information without sending a full reply. - Combine with a message send operation to create a react-then-reply automation flow. x-ai-capabilities: confirmation: type: None security_info: data_handling: - ResourceStateUpdate servers: - description: '' url: https://api.sendpulse.com/telegram /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_8' 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 servers: - description: '' url: https://api.sendpulse.com/whatsapp /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_7' 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. servers: - description: '' url: https://api.sendpulse.com/whatsapp /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_7' 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. servers: - description: '' url: https://api.sendpulse.com/whatsapp /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_7' 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. servers: - description: '' url: https://api.sendpulse.com/whatsapp components: schemas: ContactAttributeValue: type: object properties: id: type: integer name: type: string status: type: integer description: '| Status * 0 — inactive (deleted by user) * 1 — active * 2 — hidden' type: type: integer mandatory: type: boolean contactCardShow: type: boolean order: type: integer options: type: array items: oneOf: - type: string - type: integer description: Items of "List" field type value: properties: type: type: string description: Field type value: type: string description: Field value description: '' default: type: boolean description: '' DealHistory: type: object properties: id: type: integer userId: type: integer eventData: type: array eventType: type: string eventTime: type: string format: date-time currentData: type: object properties: contactFirstName: type: string contactLastName: type: string 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 Contact: type: object properties: id: type: integer description: Contact ID userId: type: integer description: ID of user who created the contact sourceType: type: string enum: - manually - chatbot - subscription_form - landing - a360 - payments responsibleId: type: integer description: ID of user responsible for the contact. Can be obtained in the “Get list of invited users” method firstName: type: string description: Contact first name lastName: type: string description: Contact last name dealsQty: type: integer externalContactId: type: string comments: items: $ref: '#/components/schemas/ContactComment' tags: items: $ref: '#/components/schemas/ContactTag' phones: items: $ref: '#/components/schemas/ContactPhone' emails: items: $ref: '#/components/schemas/ContactEmail' messengers: items: $ref: '#/components/schemas/ContactMessenger' attributes: items: $ref: '#/components/schemas/ContactAttributeValue' history: items: $ref: '#/components/schemas/ContactHistory' tasks: type: array items: type: integer createdAt: type: string format: date-time description: The date and time the contact was created. Output in YYYY-MM-DD hh:mm:ss format with fractions of a second and time zone updatedAt: type: string format: date-time attachments: $ref: '#/components/schemas/EntityAttachment' ContactEmail: type: object properties: id: type: integer description: Email address ID email: type: string description: Email address isMain: type: boolean description: Determines whether the email address is the main one ContactHistory: type: object properties: id: type: integer userId: type: integer contactId: type: integer eventType: type: string eventTime: type: string format: date-time eventData: type: object properties: dealName: type: string FilterExpressionProperty: type: string description: '| Possible values: - eq (=) - neq (!=) - gt (>) - gte (>=) - lt (<) - lte (<=) - like - in (check among list of values).' ContactPhone: type: object properties: id: type: integer description: Contact phone ID phone: type: string isMain: type: boolean EntityAttachment: type: object properties: id: type: integer link: type: string entityId: type: number entityType: type: string createdAt: type: string updatedAt: type: string ContactTag: type: object properties: id: type: integer description: Tag ID name: type: string description: Tag name colorText: type: string colorBackground: type: string contactCount: type: integer description: Number of contacts associated with the tag taskCount: type: integer description: Number of tasks associated with a tag Deal: type: object properties: id: type: integer description: Deal ID pipelineId: type: integer description: Pipeline ID status: $ref: '#/components/schemas/DealStatusProperty' stepId: type: integer description: Pipeline step ID responsibleId: type: integer description: ID of the responsible for the deal user. Can be obtained in the “Get list of invited users” method number: type: integer description: Deal number, the number is generated automatically according to the order in which deal was created. Used in deal name if a custom value has not been specified name: type: string description: Deal name price: type: number description: Deal price currency: type: string description: 'Deal currency. Example: UAH, USD, EUR' profit: type: number description: Deal profit in major currency units hasExpense: type: boolean description: Shows if the deal has at least one expense order: type: integer description: Deal order sourceType: $ref: '#/components/schemas/DealSourceType' sourceId: type: integer description: ID of external source history: items: $ref: '#/components/schemas/DealHistory' comments: items: $ref: '#/components/schemas/DealComment' attributes: items: $ref: '#/components/schemas/DealAttributeValue' expiration: $ref: '#/components/schemas/DealExpiration' attachments: $ref: '#/components/schemas/EntityAttachment' tasks: type: array items: type: integer createdAt: type: string format: date-time description: The date and time the transaction was created. Output in YYYY-MM-DD hh:mm:ss format with fractions of a second and time zone updatedAt: type: string format: date-time description: The date and time the transaction information was last updated. Output in YYYY-MM-DD hh:mm:ss format with fractions of a second and time zone DealSourceType: type: object properties: id: type: integer description: '' name: type: string description: '' ContactComment: type: object properties: id: type: integer userId: type: integer text: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time attachments: $ref: '#/components/schemas/EntityAttachment' childCount: type: integer childUsers: type: array items: type: integer DealAttributeValue: type: object properties: id: type: integer pipelineId: type: integer name: type: string status: type: integer type: type: integer mandatory: type: boolean order: type: integer options: type: array description: Items of "List" field type items: oneOf: - type: string - type: integer value: properties: value: type: string MessengerTypeProperty: type: integer description: '| Messenger type. Possible values: * 1 — Telegram * 2 — Facebook * 4 — Instagram * 5 — WhatsApp * 6 — Viber' AttributesProperty: type: array description: Filter by attributes only items: type: object properties: id: type: string description: Attribute ID expression: $ref: '#/components/schemas/FilterExpressionProperty' value: maxLength: 255 description: Can have string value or array of strings DealExpiration: type: object properties: date: type: string format: date description: Deal expiration date time: type: - string - 'null' format: time description: Deal expiration time dateTime: type: string format: date-time description: Deal expiration DateTime notificationEnabled: type: boolean description: Is notification enabled notifyIn: type: - string - 'null' description: Notify before deal expires (when notification is enabled). Allowed values - 0(not selected), 15min, 30min, 1h, 2h, 3h, 6h, 12h, 24h, 2d, 3d, 4d, 5d, 6d, 7d expired: type: boolean description: The deal has expired expires_within_day: type: boolean description: The deal expires within 24 hours DealStatusProperty: type: integer description: '| Step status * 0 — inactive (deleted by user) * 1 — active * 2 - completed deal as “Unsuccessful” * 3 - completed deal as “Successful”' DealComment: type: object properties: id: type: integer userId: type: integer eventData: type: object properties: text: type: string status: type: integer eventTime: type: string createdAt: type: string updatedAt: type: string attachments: items: $ref: '#/components/schemas/EntityAttachment' childCount: type: integer childUsers: type: array items: type: integer Contact_2: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled" channel_data: type: object properties: id: type: string name: type: string first_name: type: string last_name: type: - string - 'null' profile_pic: type: - string - 'null' locale: type: - string - 'null' gender: type: - string - 'null' tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 unsubscribed_at: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Campaign: properties: id: type: string bot_id: type: string title: type: string message_tag: type: string enum: - HUMAN_AGENT - CUSTOMER_FEEDBACK description: '' example: HUMAN_AGENT message_notification_type: type: string enum: - REGULAR - SILENT_PUSH - NO_PUSH description: '' example: REGULAR send_at: type: string example: 2020-12-11 21:00:00+00:00 messages: type: array description: A list of messages to send items: type: object properties: type: type: string enum: - text - media_img - media_file - media_audio - media_video - template - list description: '* `text` - text message ' example: text data: type: object description: '' properties: attachment: type: object properties: payload: type: object properties: elements: type: array items: type: object properties: filename: type: string is_external_attachment: type: boolean created_at: type: string example: 2020-12-11 21:00:00+00:00 SuccessResponse: properties: success: type: boolean data: anyOf: - type: array items: type: object - type: object - type: boolean type: object Message: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://developers.facebook.com/docs/messenger-platform/reference/send-api/#message example: text: hello direction: type: integer enum: - 1 - 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" delivered_at: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 opened_at: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 redirected_at: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Contact_3: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" channel_data: type: object properties: id: type: integer user_name: type: - string - 'null' first_name: type: string last_name: type: - string - 'null' name: type: string profile_pic: type: - string - 'null' tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Message_2: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://core.telegram.org/bots/api#message example: text: hello direction: type: integer enum: IN: 1 OUT: 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 description: "\n * `1` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" created_at: type: string example: 2020-12-11 21:00:00+00:00 Contact_4: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" online: type: boolean channel_data: type: object properties: id: type: integer full_name: type: string url: type: - string - 'null' example: null lang: type: - string - 'null' example: null tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 SuccessResponse_2: properties: success: type: boolean data: anyOf: - type: array items: type: object - type: object - type: boolean - type: string - type: integer type: object Message_3: properties: id: type: string contact_id: type: string bot_id: type: string campaign: type: - object - 'null' example: null chain: type: - object - 'null' example: null reject_reason: type: - string - 'null' example: null data: type: object description: https://core.telegram.org/bots/api#message example: type: type text: hello subscriber_id: d86e2ca7-0000-0000-1111-1f1f32d0f0b1 direction: type: integer enum: IN: 1 OUT: 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" type: type: string enum: - text - image - document description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" created_at: type: string example: 2020-12-11 21:00:00+00:00 Contact_5: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" channel_data: type: object properties: username: type: - string - 'null' first_name: type: string last_name: type: - string - 'null' name: type: string language_code: type: - string - 'null' tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 telegram_id: type: string created_at: type: string example: 2020-12-11 21:00:00+00:00 Message_4: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://core.telegram.org/bots/api#message example: text: hello direction: type: integer enum: - 1 - 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" created_at: type: string example: 2020-12-11 21:00:00+00:00 sent_by: type: - object - 'null' description: Operator data, which send a message type: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 description: "Internal type of message\n\n * `1` - 'Internal chat',\n * `2` - 'External chat',\n * `3` - 'Payment',\n * `4` - 'Campaign',\n * `5` - 'Operator',\n * `6` - 'Operator note',\n * `7` - 'Feed comment',\n " channel: type: string enum: - ma - ma_chat - api - rss - echo - jivo - open_ai - payment Contact_6: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" channel_data: type: object properties: id: type: string conversation_id: type: string display_name: type: string username: type: string profile_image: type: - string - 'null' tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Message_5: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://core.telegram.org/bots/api#message example: text: hello direction: type: integer enum: IN: 1 OUT: 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" created_at: type: string example: 2020-12-11 21:00:00+00:00 Contact_7: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" channel_data: type: object properties: id: type: integer name: type: - string - 'null' avatar: type: - string - 'null' country: type: string language: type: string tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Message_6: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://core.telegram.org/bots/api#message example: text: hello direction: type: integer enum: IN: 1 OUT: 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" created_at: type: string example: 2020-12-11 21:00:00+00:00 Contact_8: properties: id: type: string bot_id: type: string status: type: integer enum: - 1 - 2 - 3 - 4 description: "\n * `1` - active\n\n * `2` - unsubscribed\n\n * `3` - disabled\n\n * `4` - blocked by user" channel_data: type: object properties: username: type: - string - 'null' first_name: type: string last_name: type: - string - 'null' name: type: string language_code: type: - string - 'null' tags: type: array uniqueItems: true items: type: string variables: type: object description: 'variable_name: variable_value' is_chat_opened: type: boolean last_activity_at: type: string example: 2020-12-11 21:00:00+00:00 automation_paused_until: type: - string - 'null' example: 2020-12-11 21:00:00+00:00 created_at: type: string example: 2020-12-11 21:00:00+00:00 Message_7: properties: id: type: string contact_id: type: string bot_id: type: string campaign_id: type: - string - 'null' data: type: object description: https://core.telegram.org/bots/api#message example: text: hello direction: type: integer enum: IN: 1 OUT: 2 description: "\n * `1` - in\n\n * `2` - out" status: type: integer enum: - 1 description: "\n * `1` - new\n\n * `2` - sent\n\n * `3` - delivered\n\n * `4` - opened\n\n * `5` - redirected\n\n * `6` - rejected" is_paid: type: boolean price_cbp: type: - object - 'null' description: Conversation Based Price example: price: 0.006 currency: USD origin_type: user_initiated is_free_conversation: false country_code: TR created_at: type: string example: 2020-12-11 21:00:00+00:00 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: API Key description: 'Static API Key authentication. A long-lived token generated manually in the SendPulse account settings. ' x-ai-description: 'Permanent authentication token. Ideal for simple integrations without token refresh logic. ' outh2: type: oauth2 description: OAuth 2.0 Client Credentials flow for temporary access tokens. flows: clientCredentials: tokenUrl: https://api.sendpulse.com/oauth/access_token scopes: {} x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret. Provides temporary tokens (valid for 1 hour) for enhanced security. ' oauth2: type: oauth2 description: OAuth 2.0 Client Credentials flow for temporary access tokens. flows: clientCredentials: tokenUrl: https://api.sendpulse.com/oauth/access_token scopes: {} x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret. Provides temporary tokens (valid for 1 hour) for enhanced security. ' x-refined-from: - sendpulse-crm-openapi.yml - sendpulse-facebook-openapi.yml - sendpulse-instagram-openapi.yml - sendpulse-live-chat-openapi.yml - sendpulse-sms-openapi.yml - sendpulse-telegram-openapi.yml - sendpulse-tiktok-openapi.yml - sendpulse-viber-chatbot-openapi.yml - sendpulse-whatsapp-openapi.yml