{"openapi":"3.0.0","info":{"title":"Chatbots service API","description":"Using the API for Chatbots, you can integrate your system with SendPulse\u2019s chatbots service and get detailed information about your account, bots, dialogs.\n\n            \nOn the right, there is a button for authorizing requests made on this page. Click \u201cAuthorize,\u201d then insert the ID and Secret from your account.\n\n            \nTo perform a request directly from the page, click the \"Try it out\" button within each method block. Then fill in input fields if any (for URL parameters, the description is right below the URL request; for body parameters, the description is under the \u201cScheme\u201d button to the right of the example), and click \u201cRun.\u201d You'll find the server response and description of received parameters below.\n        ","version":"0.0.1"},"servers":[{"url":"https:\/\/api.sendpulse.com\/chatbots","description":""}],"tags":[{"name":"dialogs","description":""},{"name":"account","description":""},{"name":"bots","description":""},{"name":"operator-groups","description":""},{"name":"dialog-labels","description":"Create and manage dialog labels to organize your conversations"},{"name":"operators","description":""}],"paths":{"\/dialogs":{"get":{"summary":"Get dialogs list info","description":"Returns information about your dialogs from all channels","security":[{"Authorization by API key":[]}],"tags":["dialogs"],"parameters":[{"in":"query","name":"size","description":"The limit of pagination items that will be returned","schema":{"type":"integer"}},{"in":"query","name":"skip","description":"The offset of pagination items, indicating where the current batch starts","schema":{"type":"integer"}},{"in":"query","name":"search_after","description":"The ID of the last_inbox_message element after which elements will be returned","schema":{"type":"string"}},{"in":"query","name":"order","description":"Sort order ASC or DESC","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#\/components\/schemas\/Dialog"}},"sort":{"type":"object"},"total":{"type":"integer"},"size":{"type":"integer"},"search_after":{"type":"string"},"order":{"type":"string","enum":["asc","desc"]}}}},"type":"object"}}}}}},"post":{"summary":"Search dialogs with filter","description":"Returns dialogs filtered by specified criteria. Supports filtering by label_ids and other fields.","security":[{"Authorization by API key":[]}],"tags":["dialogs"],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"filter":{"type":"object","description":"Filter object with expressions","properties":{"type":{"type":"string","description":"Filter type (and\/or)","enum":["and","or"]},"expressions":{"type":"array","description":"Array of filter expressions","items":{"type":"object","properties":{"type":{"type":"string","description":"Expression type (and\/or)","enum":["and","or"]},"expressions":{"type":"array","description":"Array of conditions","items":{"type":"object","properties":{"operator":{"type":"string","description":"Condition operator: \"in\" for array values, \"eq\" for single value","example":"in"},"field":{"type":"string","description":"Field name to filter by (e.g., label_ids)","example":"label_ids"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter value. Can be string for \"eq\" operator or array of strings for \"in\" operator"}}}}}}}}}}},"examples":{"Filter dialogs by label IDs":{"value":{"filter":{"type":"and","expressions":[{"type":"and","expressions":[{"operator":"in","field":"label_ids","value":["label_id_1","label_id_2"]}]}]}}}}}}},"responses":{"200":{"description":"Dialogs found successfully","content":{"application\/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#\/components\/schemas\/Dialog"}},"sort":{"type":"object"},"total":{"type":"integer"},"size":{"type":"integer"},"search_after":{"type":"string"},"order":{"type":"string","enum":["asc","desc"]}}}},"type":"object"}}}}}}},"\/account":{"get":{"summary":"Get account info","description":"Returns information about your current account pricing plan, the number of messages in your plan, bots, contacts, list of tags, and variables","security":[{"Authorization by API key":[]}],"tags":["account"],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/Account"}},"type":"object"}}}}}}},"\/operators":{"get":{"summary":"Get a list of operators","description":"Returns the list of operators available on the account (the account owner and all active related operators) with information about each: user ID, username, email, avatar, and online status","security":[{"Authorization by API key":[]}],"tags":["operators"],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Operator"}}}}}}}}}},"\/operators\/{operator}\/statistics\/current":{"post":{"summary":"Get current statistics for an operator","description":"Returns the current statistics for a specified operator, including active dialogs, unanswered dialogs, and assigned dialogs counts","security":[{"Authorization by API key":[]}],"tags":["operators"],"parameters":[{"in":"path","name":"operator","required":true,"description":"The operator user ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["bot_ids"],"properties":{"bot_ids":{"type":"array","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string","description":"Bot ID in ObjectId (24 hex chars) or UUID format depending on channel"},"description":"Required array of unique bot IDs, up to 1000 elements. Each bot ID must be a valid ObjectId (24 hex characters) or UUID, depending on the channel. Passed in request body to support large lists"}}}}}},"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/OperatorCurrentStatistics"}}}}}},"404":{"description":"Returned when the operator with the given ID doesn't exist or is not an operator of your account"},"422":{"description":"Request body missing, bot_ids absent, empty, exceeds 1000 elements, contains duplicates, or contains invalid bot ID (not ObjectId or UUID)"}}}},"\/operators\/{operator}\/statistics\/period":{"get":{"summary":"Get period statistics for an operator","description":"Returns statistics for a specified operator within the given date range (defaulting to last 7 days if not specified), including dialogs opened\/closed, average response time, and online duration. Both from and to are inclusive; dates must be in Y-m-d format and not in the future","security":[{"Authorization by API key":[]}],"tags":["operators"],"parameters":[{"in":"path","name":"operator","required":true,"description":"The operator user ID","schema":{"type":"integer"}},{"in":"query","name":"from","required":false,"description":"Start date, Y-m-d, not in the future. Optional, but must be passed together with to","schema":{"type":"string","format":"date"}},{"in":"query","name":"to","required":false,"description":"End date, Y-m-d, not in the future, must be >= from. Optional, but must be passed with from. When both are omitted, the last 7 days including today are used. Range must not exceed 90 days","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/OperatorPeriodStatistics"}}}}}},"404":{"description":"Returned when the operator with the given ID doesn't exist or is not an operator of your account"},"422":{"description":"Returned when invalid: bad date, only one of from\/to given, or range over 90 days"}}}},"\/operator-groups":{"get":{"summary":"Get a list of operator groups","description":"Returns the list of operator groups created on the account with information about each: group ID, name, and the account owner's user ID","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/OperatorGroup"}}}}}}}}},"post":{"summary":"Create an operator group","description":"Creates a new operator group with the given name","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/OperatorGroup"}}}}}},"422":{"description":"Returned when the request is invalid, e.g. the name is missing, exceeds 255 characters, or an operator group with this name already exists"}}}},"\/operator-groups\/{operator_group}":{"put":{"summary":"Update an operator group","description":"Updates the name of the selected operator group","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"parameters":[{"in":"path","name":"operator_group","required":true,"description":"The operator group ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/OperatorGroup"}}}}}},"404":{"description":"Returned when the operator group with the given ID doesn't exist"},"422":{"description":"Returned when the request is invalid, e.g. the name is missing, exceeds 255 characters, or an operator group with this name already exists"}}},"delete":{"summary":"Delete an operator group","description":"Deletes the selected operator group along with all its members","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"parameters":[{"in":"path","name":"operator_group","required":true,"description":"The operator group ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"boolean"}}}}}},"404":{"description":"Returned when the operator group with the given ID doesn't exist"}}}},"\/operator-groups\/{operator_group}\/members":{"get":{"summary":"Get a list of operator group members","description":"Returns the list of members of the selected operator group with information about each: member ID, operator ID, auto distribution settings, and operator profile data","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"parameters":[{"in":"path","name":"operator_group","required":true,"description":"The operator group ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/OperatorGroupMember"}}}}}}},"404":{"description":"Returned when the operator group with the given ID doesn't exist"}}},"post":{"summary":"Add members to an operator group","description":"Adds the selected operators to the operator group. Operators already in the group are skipped","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"parameters":[{"in":"path","name":"operator_group","required":true,"description":"The operator group ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["operator_ids"],"properties":{"operator_ids":{"type":"array","minItems":1,"items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"boolean"}}}}}},"404":{"description":"Returned when the operator group with the given ID doesn't exist"},"422":{"description":"Returned when the request is invalid, e.g. operator_ids is empty or contains an operator ID that doesn't exist on the account"}}}},"\/operator-groups\/{operator_group}\/members\/{operator_group_member}":{"delete":{"summary":"Remove a member from an operator group","description":"Removes the selected member from the operator group","security":[{"Authorization by API key":[]}],"tags":["operator-groups"],"parameters":[{"in":"path","name":"operator_group","required":true,"description":"The operator group ID","schema":{"type":"string"}},{"in":"path","name":"operator_group_member","required":true,"description":"The operator group member ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"boolean"}}}}}},"404":{"description":"Returned when the operator group or the member doesn't exist, or the member doesn't belong to the specified operator group"}}}},"\/dialog-labels":{"get":{"summary":"Get all dialog labels for account","description":"Returns the list of all dialog labels created on the account","security":[{"Authorization by API key":[]}],"tags":["dialog-labels"],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#\/components\/schemas\/DialogLabel"}}}}}}}}}}},"post":{"summary":"Create a dialog label","description":"Creates a new dialog label with emoji and name","security":[{"Authorization by API key":[]}],"tags":["dialog-labels"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emoji","name"],"properties":{"emoji":{"type":"string","description":"A single emoji character"},"name":{"type":"string","maxLength":24}}}}}},"responses":{"200":{"description":"Label created successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/DialogLabel"}}}}}},"400":{"description":"Label limit reached (maximum 16 labels per account)"},"422":{"description":"Validation failed, e.g., missing required fields or invalid emoji"}}}},"\/dialog-labels\/{dialog_label}":{"put":{"summary":"Update a dialog label","description":"Updates emoji and name of an existing dialog label","security":[{"Authorization by API key":[]}],"tags":["dialog-labels"],"parameters":[{"in":"path","name":"dialog_label","required":true,"description":"The dialog label ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emoji","name"],"properties":{"emoji":{"type":"string","description":"A single emoji character"},"name":{"type":"string","maxLength":24}}}}}},"responses":{"200":{"description":"Label updated successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#\/components\/schemas\/DialogLabel"}}}}}},"404":{"description":"Label not found"},"422":{"description":"Validation failed, e.g., invalid emoji or name"}}},"delete":{"summary":"Delete a dialog label","description":"Deletes a label. The label is also removed from all dialogs where it was assigned.","security":[{"Authorization by API key":[]}],"tags":["dialog-labels"],"parameters":[{"in":"path","name":"dialog_label","required":true,"description":"The dialog label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Label deleted successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"boolean"}}}}}},"404":{"description":"Label not found"}}}},"\/dialog-labels\/assign":{"post":{"summary":"Assign labels to dialog","description":"Replace the set of labels assigned to a dialog. An empty array removes all labels.","security":[{"Authorization by API key":[]}],"tags":["dialog-labels"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["dialog_id","label_ids"],"properties":{"dialog_id":{"type":"string","description":"The dialog ID"},"label_ids":{"type":"array","maxItems":16,"items":{"type":"string"},"description":"Array of label IDs to assign to the dialog"}}}}}},"responses":{"200":{"description":"Labels assigned successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"boolean"}}}}}},"422":{"description":"Validation failed: invalid or unknown dialog ID, invalid label IDs or label does not exist"}}}},"\/bots":{"get":{"summary":"Get a list of connected bots","description":"Returns lists of bots with information about each: bot ID, channel information, number of received and unread messages, bot status, and creation date","security":[{"Authorization by API key":[]}],"tags":["bots"],"responses":{"200":{"description":"Operation successful","content":{"application\/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Bot"}}},"type":"object"}}}}}}}},"components":{"securitySchemes":{"Authorization by API key":{"type":"http","scheme":"bearer","description":"Paste your API key in the format sp_apikey_*** from the https:\/\/login.sendpulse.com\/settings\/api section"}},"schemas":{"SuccessResponse":{"properties":{"success":{"type":"boolean"},"data":{"anyOf":[{"type":"array","items":{"type":"object"}},{"type":"object"},{"type":"boolean"}]}},"type":"object"},"Dialog":{"properties":{"_id":{"type":"string"},"bot_id":{"type":"string"},"contact":{"type":"object","properties":{"id":{"type":"string"},"full_name":{"type":"string"},"profile_pic":{"type":"string"}}},"last_inbox_message":{"type":"object","properties":{"text":{"type":"string"},"date":{"type":"string","example":"2020-12-12T00:00:00+03:00"}}},"last_outbox_message":{"type":"object","properties":{"text":{"type":"string"},"date":{"type":"string","example":"2020-12-12T00:00:00+03:00"}}},"service":{"type":"integer"},"user_id":{"type":"integer"},"inbox_unread_count":{"type":"integer"},"is_chat_opened":{"type":"boolean"},"created_at":{"type":"string","example":"2020-12-12T00:00:00+03:00"},"updated_at":{"type":"string","example":"2020-12-12T00:00:00+03:00"},"label_ids":{"type":"array","items":{"type":"string"},"description":"IDs of labels assigned to the dialog"}}},"Account":{"properties":{"tariff":{"type":"object","description":"`-1` - unlimited","properties":{"code":{"type":"string","example":"messengers500"},"max_bots":{"type":"integer","example":-1},"max_contacts":{"type":"integer","example":500},"max_messages":{"type":"integer","example":-1},"max_tags":{"type":"integer","example":-1},"max_variables":{"type":"integer","example":-1},"branding":{"type":"boolean","example":false},"is_exceeded":{"type":"boolean","example":false},"is_expired":{"type":"boolean"},"expired_at":{"type":"string","example":"2026-01-15T11:11:11+00:00"}}},"statistics":{"type":"object","description":"","properties":{"messages":{"type":"integer"},"bots":{"type":"integer"},"contacts":{"type":"integer"},"variables":{"type":"integer"},"active_count_by_last_month":{"type":"integer"},"active_count_by_current_tariff_period":{"type":"integer"}}},"services":{"type":"array","description":"\n                    * `1` - Messenger\n\n                    * `3` - Telegram\n\n                    * `4` - WhatsApp\n\n                    * `5` - Instagram\n\n                    * `6` - Viber\n\n                    * `7` - Livechat\n\n                    * `8` - TikTok\n\n                    * `1000` - Bridge\n\n                    * `1001` - Telegram personal\n\n                ","items":{"type":"integer"},"example":[1,3,5]}}},"Operator":{"type":"object","properties":{"user_id":{"type":"integer","description":"The operator user ID"},"username":{"type":"string","description":"The operator full name"},"email":{"type":"string","description":"The operator email"},"avatar":{"type":"string","nullable":true,"description":"The operator avatar URL"},"online":{"type":"boolean","nullable":true,"description":"Whether the operator currently has an active websocket session"},"status":{"type":"string","description":"\n                    * `active_online` - active and online\n\n                    * `active_offline` - active but offline\n\n                    * `offline` - offline\n\n                    * `absent` - absent\n\n                "}}},"OperatorGroup":{"type":"object","properties":{"id":{"type":"string","description":"The operator group ID"},"name":{"type":"string","description":"The operator group name"},"user_id":{"type":"integer","description":"The account owner's user ID"}}},"OperatorGroupMember":{"type":"object","properties":{"member_id":{"type":"string","description":"The operator group member ID"},"operator_id":{"type":"integer","description":"The operator ID"},"auto_distribution_enabled":{"type":"boolean","description":"Whether auto distribution is enabled for the operator"},"auto_distribution_limit":{"type":"integer","nullable":true,"description":"The auto distribution limit for the operator"},"username":{"type":"string","nullable":true,"description":"The operator full name"},"email":{"type":"string","nullable":true,"description":"The operator email"},"avatar":{"type":"string","nullable":true,"description":"The operator avatar URL"}}},"DialogLabel":{"type":"object","properties":{"id":{"type":"string","description":"The dialog label ID"},"emoji":{"type":"string","description":"The emoji representing the label"},"name":{"type":"string","description":"The label name"}}},"OperatorCurrentStatistics":{"type":"object","properties":{"operator_id":{"type":"integer","description":"The operator ID"},"active_dialogs":{"type":"integer","description":"Number of currently active dialogs for this operator"},"unanswered_dialogs":{"type":"integer","description":"Number of currently unanswered dialogs for this operator"},"assigned_dialogs_closed":{"type":"integer","description":"Number of closed dialogs that were assigned to this operator"},"assigned_dialogs_total":{"type":"integer","description":"Total number of dialogs assigned to this operator, excluding trashed ones"}}},"OperatorPeriodStatistics":{"type":"object","properties":{"operator_id":{"type":"integer","description":"The operator ID"},"from":{"type":"string","format":"date","description":"Start date of the statistics period (Y-m-d format, UTC midnight)"},"to":{"type":"string","format":"date","description":"End date of the statistics period (Y-m-d format, UTC midnight); both from and to are included"},"opened_dialogs":{"type":"integer","description":"Number of dialogs opened during the specified period"},"opened_events":{"type":"integer","description":"Dialog open events count; may exceed opened_dialogs (dialogs can open multiple times)"},"assigned_events":{"type":"integer","description":"Dialog assignment events count"},"closed_dialogs":{"type":"integer","description":"Number of dialogs closed during the specified period"},"closed_events":{"type":"integer","description":"Dialog close events count; may exceed closed_dialogs (dialogs can close multiple times)"},"average_response_time_sec":{"type":"number","description":"Average response time in seconds (float) during the specified period"},"duration_online_sec":{"type":"integer","description":"Total time online in seconds (integer) during the specified period"}}},"Bot":{"properties":{"id":{"type":"string"},"channel_data":{"type":"object","properties":{"access_token":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"username":{"type":"string"}}},"inbox":{"type":"object","properties":{"total":{"type":"integer"},"unread":{"type":"integer"}}},"status":{"type":"integer","enum":[3,4],"description":"\n                    * `3` - active\n\n                    * `4` - inactive\n\n                "},"created_at":{"type":"string","example":"2020-12-12T00:00:00+03:00"}}}}},"security":[{"Authorization by API key":[]}]}