{"openapi":"3.0.0","paths":{"/api/companies/my":{"get":{"description":"With JWT: returns companies where the user is owner or member. With x-access-token: returns the single company bound to the token.","operationId":"getMyCompanies","parameters":[],"responses":{"200":{"description":"Companies retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"ownerId":{"type":"string"},"companyUsers":{"type":"array"},"subscriptions":{"type":"array"}}}}}}},"401":{"description":"Unauthorized - Missing or invalid JWT or access token"}},"security":[{"jwt-auth":[]}],"summary":"Get current user's companies","tags":["Companies"]}},"/api/companies/{id}":{"get":{"description":"Retrieves a specific company by its unique identifier with all relations","operationId":"getCompany","parameters":[{"name":"id","required":true,"in":"path","description":"Company unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Company retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"ownerId":{"type":"string"},"companyUsers":{"type":"array"},"subscriptions":{"type":"array"}}}}}},"400":{"description":"Invalid company ID format"},"404":{"description":"Company not found"}},"security":[{"access-token":[]}],"summary":"Get company by ID","tags":["Companies"]},"patch":{"description":"Updates an existing company. Requires company access permissions.","operationId":"updateCompany","parameters":[{"name":"id","required":true,"in":"path","description":"Company unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyDto"}}}},"responses":{"200":{"description":"Company updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid company data"},"401":{"description":"Unauthorized - Missing or invalid JWT token or insufficient permissions"},"404":{"description":"Company not found"}},"security":[{"access-token":[]}],"summary":"Update company","tags":["Companies"]}},"/api/companies/{id}/members":{"get":{"description":"Returns all workspace members including the owner (first entry, role 'owner', synthesized when the owner has no company_users row).","operationId":"getCompanyMembers","parameters":[{"name":"id","required":true,"in":"path","description":"Company unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Members retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]},"user":{"type":"object"}}}}}}},"401":{"description":"Unauthorized - Missing or invalid JWT or access token"},"404":{"description":"Company not found"}},"security":[{"access-token":[]}],"summary":"Get company members","tags":["Companies"]}},"/api/companies":{"get":{"description":"Retrieves a list of companies with optional filtering","operationId":"getCompanies","parameters":[{"name":"name","required":false,"in":"query","description":"Filter by company name","schema":{"type":"string"}},{"name":"description","required":false,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by company status (new, trial, active, inactive, churned, paused, banned)","schema":{"enum":["new","trial","active","inactive","churned","paused","banned"],"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"Filter by owner ID","schema":{"format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"userId","required":false,"in":"query","description":"Filter by user ID (owner)","schema":{"format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"search","required":false,"in":"query","description":"Free-text search over company name and description","schema":{"example":"acme","type":"string"}}],"responses":{"200":{"description":"Companies retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"ownerId":{"type":"string"}}}}}}},"400":{"description":"Invalid filter parameters"}},"security":[{"access-token":[]}],"summary":"Get all companies with filtering","tags":["Companies"]},"post":{"description":"Creates a new company. The authenticated user becomes the owner.","operationId":"createCompany","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyDto"}}}},"responses":{"201":{"description":"Company created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"ownerId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid company data"},"401":{"description":"Unauthorized - Missing or invalid JWT token"}},"security":[{"jwt-auth":[]}],"summary":"Create new company","tags":["Companies"]}},"/api/companies/{id}/logo":{"post":{"description":"Uploads a workspace logo. The image is re-encoded server-side to a 512x512 webp square. Requires owner or admin role.","operationId":"uploadCompanyLogo","parameters":[{"name":"id","required":true,"in":"path","description":"Company unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Logo uploaded; returns the updated company with logoUrl"},"400":{"description":"Empty, oversized, disallowed or undecodable file"},"401":{"description":"Unauthorized - Missing or invalid JWT token or insufficient permissions"},"404":{"description":"Company not found"}},"security":[{"access-token":[]}],"summary":"Upload company logo","tags":["Companies"]}},"/api/companies/{id}/exit":{"delete":{"description":"Removes the authenticated user from a company","operationId":"exitCompany","parameters":[{"name":"id","required":true,"in":"path","description":"Company unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"User exited company successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User exited company"},"companyId":{"type":"string"},"userId":{"type":"string"}}}}}},"401":{"description":"Unauthorized - Missing or invalid JWT token"},"404":{"description":"Company not found or user is not a member"}},"security":[{"jwt-auth":[]}],"summary":"Exit company","tags":["Companies"]}},"/api/companies/{id}/join-link/regenerate":{"post":{"description":"Rotates the company invite link. Owner/admin only; returns the new join URL.","operationId":"regenerateJoinLink","parameters":[],"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Regenerate company join link","tags":["Companies"]}},"/api/companies/join":{"post":{"description":"Adds the authenticated user to a company using the token from its join link.","operationId":"joinByToken","parameters":[],"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Join a company via invite token","tags":["Companies"]}},"/api/company-invitations/{companyId}/invitations":{"get":{"operationId":"listPendingInvitations","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"List of pending invitations"},"403":{"description":"Access denied to this company resource"}},"security":[{"jwt-auth":[]}],"summary":"List pending invitations for a company","tags":["Company Invitations"]},"post":{"operationId":"sendInvitation","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvitationDto"}}}},"responses":{"200":{"description":"Invitation sent successfully"},"400":{"description":"Invalid email or company not found"}},"security":[{"jwt-auth":[]}],"summary":"Send invitation to join company","tags":["Company Invitations"]}},"/api/company-invitations/accept":{"post":{"operationId":"acceptInvitation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvitationDto"}}}},"responses":{"200":{"description":"Invitation accepted successfully"},"400":{"description":"Invalid token or invitation already used"},"404":{"description":"Invitation not found"}},"security":[{"jwt-auth":[]}],"summary":"Accept invitation (works for both logged in users and after signup)","tags":["Company Invitations"]}},"/api/companies/{companyId}/access-tokens":{"post":{"operationId":"generateToken","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccessTokenDto"}}}},"responses":{"201":{"description":""}},"security":[{"jwt-auth":[]}],"summary":"Generate new access token for company","tags":["Access Tokens"]},"get":{"operationId":"getTokens","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"jwt-auth":[]}],"summary":"Get all access tokens for company","tags":["Access Tokens"]}},"/api/companies/{companyId}/access-tokens/{tokenId}":{"patch":{"operationId":"updateToken","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccessTokenDto"}}}},"responses":{"200":{"description":""}},"security":[{"jwt-auth":[]}],"summary":"Update access token","tags":["Access Tokens"]},"delete":{"operationId":"revokeToken","parameters":[{"name":"companyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"jwt-auth":[]}],"summary":"Revoke access token","tags":["Access Tokens"]}},"/api/assistants-new/{id}/versions/diff":{"get":{"operationId":"diffAssistantVersions","parameters":[{"name":"a","required":true,"in":"query","description":"Version id or \"live\"","schema":{"type":"string"}},{"name":"b","required":true,"in":"query","description":"Version id or \"live\"","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Diff two versions (or live state)","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/versions":{"get":{"operationId":"getAssistantVersions","parameters":[{"name":"skip","required":false,"in":"query","schema":{"type":"number"}},{"name":"take","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List assistant versions","tags":["Assistants (new)"]},"post":{"operationId":"commitAssistantVersion","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitVersionDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Commit a version","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/versions/{versionId}":{"get":{"operationId":"getAssistantVersion","parameters":[{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Get a version","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/versions/{versionId}/restore":{"post":{"operationId":"restoreAssistantVersion","parameters":[{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Restore a version","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/variants":{"get":{"operationId":"getAssistantVariants","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List draft variants","tags":["Assistants (new)"]},"post":{"operationId":"createAssistantVariant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariantDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Create a draft variant","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/variants/{variantId}/promote-preview":{"get":{"operationId":"previewAssistantVariantPromote","parameters":[{"name":"variantId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Diff draft vs primary before merge","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/variants/{variantId}/promote":{"post":{"operationId":"promoteAssistantVariant","parameters":[{"name":"variantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteVariantDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Merge draft into primary","tags":["Assistants (new)"]}},"/api/assistants-new/{id}":{"get":{"operationId":"getAssistant","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Get assistant by ID","tags":["Assistants (new)"]},"patch":{"operationId":"updateAssistant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssistantNewDto"}}}},"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Update assistant","tags":["Assistants (new)"]},"delete":{"operationId":"deleteAssistant","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Delete assistant","tags":["Assistants (new)"]}},"/api/assistants-new":{"get":{"operationId":"getAssistants","parameters":[{"name":"companyId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"folderId","required":false,"in":"query","description":"Filter by folder","schema":{"format":"uuid","type":"string"}},{"name":"q","required":false,"in":"query","schema":{"type":"string"}},{"name":"skip","required":false,"in":"query","schema":{"type":"number"}},{"name":"take","required":false,"in":"query","schema":{"type":"number"}},{"name":"includeVariants","required":false,"in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List assistants","tags":["Assistants (new)"]},"post":{"operationId":"createAssistant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssistantNewDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Create assistant","tags":["Assistants (new)"]}},"/api/assistants-new/{id}/copy":{"post":{"operationId":"copyAssistant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyAssistantNewDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Copy assistant","tags":["Assistants (new)"]}},"/api/assistant-tools-new":{"get":{"operationId":"getAssistantTools","parameters":[{"name":"assistantId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"skip","required":false,"in":"query","schema":{"type":"number"}},{"name":"take","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List assistant tools","tags":["Assistant tools (new)"]},"post":{"operationId":"createAssistantTool","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssistantToolNewDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Create assistant tool","tags":["Assistant tools (new)"]}},"/api/assistant-tools-new/{id}":{"get":{"operationId":"getAssistantTool","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Get assistant tool by ID","tags":["Assistant tools (new)"]},"patch":{"operationId":"updateAssistantTool","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssistantToolNewDto"}}}},"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Update assistant tool","tags":["Assistant tools (new)"]},"delete":{"operationId":"deleteAssistantTool","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Delete assistant tool","tags":["Assistant tools (new)"]}},"/api/assistant-tools-new/{id}/logs":{"get":{"operationId":"getAssistantToolLogs","parameters":[{"name":"skip","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"take","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List invocation logs for an assistant tool","tags":["Assistant tools (new)"]}},"/api/assistant-knowledge-new/{id}/token-usage":{"get":{"operationId":"getAssistantKnowledgeTokenUsage","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Embedding token usage for a knowledge item","tags":["Assistant knowledge (new)"]}},"/api/assistant-knowledge-new":{"get":{"operationId":"getAssistantKnowledgeItems","parameters":[{"name":"assistantId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"skip","required":false,"in":"query","schema":{"type":"number"}},{"name":"take","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"List knowledge items","tags":["Assistant knowledge (new)"]},"post":{"operationId":"createAssistantKnowledge","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssistantKnowledgeNewDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Create knowledge item","tags":["Assistant knowledge (new)"]}},"/api/assistant-knowledge-new/{id}":{"get":{"operationId":"getAssistantKnowledgeItem","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Get knowledge item by ID","tags":["Assistant knowledge (new)"]},"patch":{"operationId":"updateAssistantKnowledge","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssistantKnowledgeNewDto"}}}},"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Update knowledge item","tags":["Assistant knowledge (new)"]},"delete":{"operationId":"deleteAssistantKnowledge","parameters":[],"responses":{"200":{"description":""}},"security":[{"access-token":[]}],"summary":"Delete knowledge item","tags":["Assistant knowledge (new)"]}},"/api/assistants/{id}/originate":{"post":{"description":"Initiates an outgoing call to a specified phone number using the assistant's configured phone number. The call is processed asynchronously: a successful response means the request was accepted, not that the call has started. The call enters the telephony provider's dial queue and starts as soon as a line is free — usually within seconds, but under load it may wait up to ~5 minutes; if the wait expires, the call ends with the `not_dialed` status without dialing. The call outcome, transcript and recording appear in the call history after the call finishes, and are also delivered to the assistant's configured post-call webhooks.","operationId":"originateCall","parameters":[{"name":"id","required":true,"in":"path","description":"Assistant unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"description":"Target phone number, optional caller assistant override, and optional `dynamicVariables` forwarded to the voice assistant as `dynamic_variables` (key/value map for personalizing the conversation: customer name, order id, etc.). `callerAssistantId` must belong to the same company as the route assistant; when omitted, the route assistant is used as the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OriginateCallDto"},"examples":{"full":{"summary":"All fields (phone + caller override + dynamic variables)","value":{"phoneNumber":"+380501234567","callerAssistantId":"123e4567-e89b-12d3-a456-426614174000","dynamicVariables":{"customer_name":"John Doe","order_id":"ORD-12345","preferred_language":"en"}}},"withDynamicVariables":{"summary":"With dynamic variables (personalization)","value":{"phoneNumber":"+380501234567","dynamicVariables":{"customer_name":"John Doe","order_id":"ORD-12345","preferred_language":"en"}}},"withCallerAssistant":{"summary":"Override caller assistant","value":{"phoneNumber":"+380501234567","callerAssistantId":"123e4567-e89b-12d3-a456-426614174000"}},"minimal":{"summary":"Minimal — only phone number","value":{"phoneNumber":"+380501234567"}}}}}},"responses":{"200":{"description":"Call request accepted for processing (the call itself starts asynchronously)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"The call request was accepted and queued for dialing"},"workflowId":{"type":"string","example":"originate-call-123e4567-e89b-12d3-a456-426614174000-1717600000000","description":"Internal identifier of the accepted call request (useful when contacting support)"}}}}}},"400":{"description":"Invalid phone number format, missing required fields, or the call is blocked by a low account balance"},"401":{"description":"Unauthorized - Missing or invalid token or insufficient permissions"}},"security":[{"access-token":[]}],"summary":"Initiate outgoing call","tags":["Calls"]}},"/api/chats":{"get":{"operationId":"findMany","parameters":[{"name":"skip","required":false,"in":"query","description":"Number of items to skip for pagination","schema":{"example":0,"type":"number"}},{"name":"take","required":false,"in":"query","description":"Number of items to return","schema":{"example":20,"type":"number"}},{"name":"companyId","required":false,"in":"query","description":"Filter by company ID","schema":{"format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"messenger","required":false,"in":"query","description":"Filter by messenger channel","schema":{"example":"telegram","type":"string","enum":["instagram","telegram","telegram-bot","messenger","whatsapp","whatsapp-business","viber-echat","custom-messenger","widget","prom","rozetka","olx","playground"]}},{"name":"search","required":false,"in":"query","description":"Free-text search over chat names","schema":{"example":"john","type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous response (`nextCursor`)","schema":{"type":"string"}},{"name":"fromId","required":false,"in":"query","description":"Filter by messenger-specific sender ID","schema":{"example":"123456789","type":"string"}},{"name":"assistantId","required":false,"in":"query","description":"Filter by assigned assistant ID","schema":{"format":"uuid","example":"b2c3d4e5-f6a7-8901-bcde-f23456789012","type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated list of relations to include in the response","schema":{"example":"assistant,messages","type":"string"}},{"name":"unread","required":false,"in":"query","description":"Filter by unread state: \"true\" — only chats with unread messages, \"false\" — only fully read chats","schema":{"example":"true","type":"string"}},{"name":"isUnderAiControl","required":false,"in":"query","description":"Filter by AI control: \"true\" — only chats handled by AI, \"false\" — only chats handled by humans","schema":{"example":"true","type":"string"}},{"name":"managerId","required":false,"in":"query","description":"Filter by assigned manager: a user UUID, \"me\" (current user), or \"null\" (chats without a manager)","schema":{"example":"me","type":"string"}}],"responses":{"200":{"description":"Conversations retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Chat conversation with display name and messages"}},"totalCount":{"type":"number","description":"Total number of conversations"},"page":{"type":"object","nullable":true,"description":"Pagination information"}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"Get all conversations with optional filtering","tags":["Chats"]},"post":{"description":"Creates a new chat conversation","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatDto"}}}},"responses":{"200":{"description":"Chat created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid chat data"}},"security":[{"access-token":[]}],"summary":"Create new chat conversation","tags":["Chats"]}},"/api/chats/search":{"get":{"description":"Substring search over chat metadata within the caller's company scope. Cursor-paginated by lastMessageAt DESC. Query must be 3..100 characters.","operationId":"searchChats","parameters":[{"name":"q","required":true,"in":"query","description":"Search query (3..100 chars)","schema":{"type":"string"}},{"name":"companyId","required":false,"in":"query","description":"Restrict to a specific company (must be in access-token scope)","schema":{"type":"string"}},{"name":"messenger","required":false,"in":"query","schema":{"type":"string","enum":["instagram","telegram","telegram-bot","messenger","whatsapp","whatsapp-business","viber-echat","custom-messenger","widget","prom","rozetka","olx","playground"]}},{"name":"fromId","required":false,"in":"query","description":"Restrict to one connected account (chat.fromId), same as the list endpoint","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from previous response","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated enrichments, same contract as the list endpoint: lastMessage","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Page size (1..100)","schema":{"default":20,"type":"number"}}],"responses":{"200":{"description":"Chats matching the query, with next cursor"},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"Search chats by fromName / toName / phoneNumber","tags":["Chats"]}},"/api/chats/unread-counts":{"get":{"description":"Unread-CHAT counters (conversations with unread messages, not message totals) per connected account (fromId), per messenger and per view (unread / assigned to caller / unassigned / AI-controlled). `companyId` is required.","operationId":"getUnreadCounts","parameters":[{"name":"companyId","required":true,"in":"query","description":"Company (workspace) to count unread conversations for","schema":{"type":"string"}}],"responses":{"200":{"description":"Unread conversation counters","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":4},"byFromId":{"type":"object","additionalProperties":{"type":"number"},"example":{"6340798777":2}},"byMessenger":{"type":"object","additionalProperties":{"type":"number"},"example":{"telegram":3}},"views":{"type":"object","properties":{"unread":{"type":"number","example":4},"assigned":{"type":"number","example":1},"unassigned":{"type":"number","example":2},"happ":{"type":"number","example":1}}}}}}}},"400":{"description":"companyId is required"},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"Get unread conversation counters for sidebar badges","tags":["Chats"]}},"/api/chats/unread-total":{"get":{"description":"Number of conversations with unread messages for a single company. `companyId` is required.","operationId":"getUnreadTotal","parameters":[{"name":"companyId","required":true,"in":"query","description":"Company (workspace) to count unread conversations for","schema":{"type":"string"}}],"responses":{"200":{"description":"Unread conversation count","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","description":"Conversations with at least one unread message","example":3}}}}}},"400":{"description":"companyId is required"},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"Get total unread conversation count","tags":["Chats"]}},"/api/chats/messengers":{"get":{"description":"Active messenger integrations (Telegram, Instagram, WhatsApp, …) for the caller's company. Use the channel identity in `config` (e.g. `externalId`) as the `fromId` filter on `GET /chats`. Provider credentials are never returned.","operationId":"getMessengers","parameters":[{"name":"companyId","required":false,"in":"query","description":"Restrict to a single company you have access to","schema":{}}],"responses":{"200":{"description":"Connected messenger channels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Company integration id"},"isActive":{"type":"boolean"},"integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","example":"telegram"},"category":{"type":"string","example":"messengers"}}},"config":{"type":"object","description":"Channel identity only (externalId, username, …). No credentials.","properties":{"externalId":{"type":"string","nullable":true},"username":{"type":"string","nullable":true}}}}}},"totalCount":{"type":"number"}}}}}},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"List connected messenger channels","tags":["Chats"]}},"/api/chats/{id}":{"get":{"operationId":"findOne","parameters":[{"name":"include","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Chat retrieved successfully","content":{"application/json":{"schema":{"type":"object","nullable":true,"description":"Chat details with messages or null if not found"}}}},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Get specific chat by ID with messages","tags":["Chats"]},"patch":{"description":"Updates an existing chat conversation","operationId":"update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChatDto"}}}},"responses":{"200":{"description":"Chat updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid chat data"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Update chat conversation","tags":["Chats"]},"delete":{"description":"Deletes a chat conversation and all associated messages","operationId":"delete","parameters":[],"responses":{"200":{"description":"Chat deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Chat deleted successfully"},"id":{"type":"string"}}}}}},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Delete chat conversation","tags":["Chats"]}},"/api/chats/{id}/ai-suggestion":{"post":{"operationId":"suggestAiReply","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestAiReplyDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"tags":["Chats"]}},"/api/chats/{id}/ai-control":{"patch":{"description":"Enables or disables AI handling for the chat. When disabling, you may optionally specify `aiDisableReason`; if omitted, it defaults to `manual`.","operationId":"toggleAiControl","parameters":[],"requestBody":{"required":true,"description":"AI control state and optional disable reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleAiControlDto"},"examples":{"disableManual":{"summary":"Disable AI (manual)","value":{"isUnderAiControl":false,"aiDisableReason":"manual"}},"disableAuto":{"summary":"Disable AI (auto)","value":{"isUnderAiControl":false,"aiDisableReason":"auto"}},"enable":{"summary":"Enable AI","value":{"isUnderAiControl":true}}}}}},"responses":{"200":{"description":"AI control toggled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message about AI control status","example":"ai disabled"},"aiControlEnabled":{"type":"boolean","description":"Current AI control status","example":false}}}}}},"400":{"description":"Invalid AI control data"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Toggle AI control for chat conversation","tags":["Chats"]}},"/api/chats/{id}/assign-assistant":{"patch":{"operationId":"assignAssistant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignAssistantDto"}}}},"responses":{"200":{"description":"Assistant assigned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"chat":{"type":"object","description":"Updated chat with assigned assistant"}}}}}},"400":{"description":"Invalid assistant ID"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Assign assistant to chat conversation","tags":["Chats"]}},"/api/chats/{id}/unassign-assistant":{"patch":{"operationId":"unassignAssistant","parameters":[],"responses":{"200":{"description":"Assistant unassigned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"chat":{"type":"object","description":"Updated chat without assistant"}}}}}},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Unassign assistant from chat conversation","tags":["Chats"]}},"/api/chats/{id}/read":{"post":{"description":"Resets unread counter to 0 and stamps lastReadAt with the current time.","operationId":"markAsRead","parameters":[],"responses":{"200":{"description":"Chat marked as read"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Mark chat as read","tags":["Chats"]}},"/api/chats/{id}/unread":{"post":{"description":"Rewinds lastReadAt to the latest outgoing message and recomputes the unread counter based on incoming messages after that point.","operationId":"markAsUnread","parameters":[],"responses":{"200":{"description":"Chat marked as unread"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Mark chat as unread","tags":["Chats"]}},"/api/chats/{id}/media":{"get":{"description":"Paginated media (images, files, audio) sent in a conversation, filterable by storage bucket.","operationId":"getChatMedia","parameters":[{"name":"bucket","required":true,"in":"query","description":"Media bucket to list: media — photos and videos, files — documents, voice — audio messages","schema":{"example":"media","type":"string","enum":["media","files","voice"]}},{"name":"take","required":false,"in":"query","description":"Number of items to return","schema":{"example":20,"type":"number"}},{"name":"skip","required":false,"in":"query","description":"Number of items to skip for pagination","schema":{"example":0,"type":"number"}}],"responses":{"200":{"description":"Media attachments retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Media attachment metadata"}},"totalCount":{"type":"number","description":"Total number of media attachments"}}}}}},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"List media attachments in a chat","tags":["Chats"]}},"/api/messages":{"get":{"operationId":"findMany","parameters":[{"name":"skip","required":false,"in":"query","description":"Number of items to skip for pagination","schema":{"example":0,"type":"number"}},{"name":"take","required":false,"in":"query","description":"Number of items to return","schema":{"example":20,"type":"number"}},{"name":"chatId","required":true,"in":"query","description":"ID of the chat to list messages from","schema":{"format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous response (`nextCursor`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Messages retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"Message entity with timestamp ordering"}}}}},"400":{"description":"Chat ID is required"},"401":{"description":"Unauthorized access"}},"security":[{"access-token":[]}],"summary":"Get messages for specific chat","tags":["Messages"]},"post":{"description":"Creates a new message in a chat conversation","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessageDto"}}}},"responses":{"201":{"description":"Message created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"chatId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid message data or chat not found"}},"security":[{"access-token":[]}],"summary":"Create new message","tags":["Messages"]}},"/api/messages/last":{"get":{"description":"Returns the most recent message for each of the specified chat IDs","operationId":"findLastMessages","parameters":[{"name":"chatIds","required":true,"in":"query","description":"Comma-separated list of chat UUIDs","schema":{"example":"123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001","type":"string"}}],"responses":{"200":{"description":"Last messages retrieved successfully. Returns Record<chatId, IMessage>"},"400":{"description":"Invalid chat ID format"}},"security":[{"access-token":[]}],"summary":"Get last message for each chat","tags":["Messages"]}},"/api/messages/search":{"get":{"description":"Substring search over message text within the caller's company scope, backed by a pg_trgm GIN index. System messages and function-call frames are excluded. Cursor-paginated by createdAt DESC.","operationId":"searchMessages","parameters":[{"name":"q","required":true,"in":"query","description":"Search query (3..100 chars)","schema":{"type":"string"}},{"name":"companyId","required":false,"in":"query","description":"Restrict to a specific company (must be in access-token scope)","schema":{"type":"string"}},{"name":"chatId","required":false,"in":"query","description":"Restrict to a specific chat","schema":{"type":"string"}},{"name":"messenger","required":false,"in":"query","schema":{"type":"string","enum":["instagram","telegram","telegram-bot","messenger","whatsapp","whatsapp-business","viber-echat","custom-messenger","widget","prom","rozetka","olx","playground"]}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from previous response","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Page size (1..100)","schema":{"default":20,"type":"number"}}],"responses":{"200":{"description":"Messages matching the query, with next cursor"},"400":{"description":"Invalid query (must be 3..100 chars)"}},"security":[{"access-token":[]}],"summary":"Search messages by text","tags":["Messages"]}},"/api/messages/{id}":{"get":{"description":"Retrieves a specific message by its unique identifier","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Message unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Message retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"chatId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid message ID format"},"404":{"description":"Message not found"}},"security":[{"access-token":[]}],"summary":"Get message by ID","tags":["Messages"]},"patch":{"description":"Updates an existing message's content","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","description":"Message unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMessageDto"}}}},"responses":{"200":{"description":"Message updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid message data"},"404":{"description":"Message not found"}},"security":[{"access-token":[]}],"summary":"Update message","tags":["Messages"]},"delete":{"description":"Deletes a message from a chat conversation","operationId":"delete","parameters":[{"name":"id","required":true,"in":"path","description":"Message unique identifier","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Message deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Message deleted successfully"},"id":{"type":"string"}}}}}},"404":{"description":"Message not found"}},"security":[{"access-token":[]}],"summary":"Delete message","tags":["Messages"]}},"/api/chats/{id}/meta":{"put":{"description":"Overwrites the entire meta object on the chat (labels, comments, and free-form keys).","operationId":"replaceChatMeta","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChatMetaDto"}}}},"responses":{"200":{"description":"Chat meta replaced"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Replace chat meta","tags":["Chats"]}},"/api/chats/{id}/meta/labels":{"post":{"description":"Appends a label to chat.meta.labels (deduplicated).","operationId":"addChatLabel","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddChatLabelDto"}}}},"responses":{"200":{"description":"Label added"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Add label to chat","tags":["Chats"]}},"/api/chats/{id}/meta/labels/{label}":{"delete":{"operationId":"removeChatLabel","parameters":[{"name":"label","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Label removed (idempotent)"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Remove label from chat","tags":["Chats"]}},"/api/chats/{id}/meta/comments":{"post":{"description":"Appends a manager comment to chat.meta.comments. AuthorId is taken from the JWT.","operationId":"addChatComment","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddChatCommentDto"}}}},"responses":{"200":{"description":"Comment added"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Add comment to chat","tags":["Chats"]}},"/api/chats/{id}/meta/comments/{commentId}":{"delete":{"operationId":"removeChatComment","parameters":[{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Comment removed (idempotent)"},"401":{"description":"Unauthorized access"},"404":{"description":"Chat not found"}},"security":[{"access-token":[]}],"summary":"Remove comment from chat","tags":["Chats"]}},"/api/chats/{id}/context":{"get":{"operationId":"getContext","parameters":[],"responses":{"200":{"description":""}},"tags":["ChatContext"]}},"/api/assistant-tools-new/{id}/test":{"post":{"operationId":"testAssistantTool","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestToolDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Fire a test call of a webhook tool","tags":["Assistant tools (new)"]}},"/api/assistant-knowledge-new/query":{"post":{"operationId":"queryAssistantKnowledge","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeQueryDto"}}}},"responses":{"201":{"description":""}},"security":[{"access-token":[]}],"summary":"Test-query an assistant's vector knowledge","tags":["Assistant Knowledge"]}},"/api/auth/me":{"get":{"description":"Returns the authenticated user's information based on JWT token","operationId":"me","parameters":[],"responses":{"200":{"description":"User information retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing JWT token"}},"security":[{"jwt-auth":[]}],"summary":"Get current user information","tags":["Auth"]}},"/api/auth/refresh":{"post":{"description":"Generates new access and refresh tokens using a valid refresh token","operationId":"refreshTokens","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Valid refresh token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}},"required":["refreshToken"]}}}},"responses":{"200":{"description":"Tokens refreshed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refreshToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"expiresIn":{"type":"string","example":"15m"}}}}}},"400":{"description":"Invalid or expired refresh token"},"401":{"description":"Unauthorized - Invalid refresh token"}},"summary":"Refresh access token","tags":["Auth"]}},"/api/auth/sign-up":{"post":{"description":"Creates a new user account with email and password","operationId":"signUp","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAuthDto"}}}},"responses":{"200":{"description":"User registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refreshToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"expiresIn":{"type":"string","example":"15m"}}}}}},"400":{"description":"Invalid email format or user already exists"}},"summary":"Sign up with email","tags":["Auth"]}},"/api/auth/sign-in":{"post":{"description":"Authenticates user with email and password, returns JWT tokens","operationId":"signIn","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAuthDto"}}}},"responses":{"200":{"description":"User authenticated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refreshToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"expiresIn":{"type":"string","example":"15m"}}}}}},"400":{"description":"Invalid email or password"},"401":{"description":"Invalid credentials"}},"summary":"Sign in with email","tags":["Auth"]}}},"info":{"title":"Happ Platform API - Public","description":"## Happ Platform API\n\nConnect messenger channels (Telegram, Instagram, WhatsApp) and a voice assistant to your business.\n\n### Authentication\n\n1. Sign in (`POST /api/auth/sign-in`) to get a JWT — or open your account at [my.happ.tools](https://my.happ.tools).\n2. Generate an **Access Token**: `POST /api/companies/{companyId}/access-tokens` (JWT required).\n3. Send it on every request:\n   ```\n   X-Access-Token: happ_your_token_here\n   ```\n\nAn Access Token is scoped to a **single company/team** — it only reaches that company's resources. For example `GET /api/companies` returns just that company, not every company you belong to.\n\nUse the Access Token to integrate. JWT (`Authorization: Bearer <jwt>`) is for the web/admin panel and the bootstrap auth endpoints only.\n\n### Guides & interactive examples\n\nStep-by-step guides, quickstart and live examples: **[docs.happ.tools](https://docs.happ.tools/en/docs/api)**\n\n### Building with an AI assistant\n\nUsing Claude, Cursor or Copilot to integrate? Point it at the machine-readable spec — `GET /api/swagger-json` — and the docs index [docs.happ.tools/llms.txt](https://docs.happ.tools/llms.txt). Both are kept in sync with this reference.","version":"1.0","contact":{}},"tags":[{"name":"Auth","description":"Sign up, sign in, and token refresh"},{"name":"Companies","description":"Company (workspace) management and members"},{"name":"Company Invitations","description":"Invite users to a company"},{"name":"Access Tokens","description":"Long-lived API tokens for integrations"},{"name":"Assistants (new)","description":"AI assistant configuration"},{"name":"Assistant tools (new)","description":"Webhook-backed tools an assistant can call"},{"name":"Assistant knowledge (new)","description":"Knowledge base items powering RAG answers"},{"name":"Chats","description":"Conversations across all connected channels"},{"name":"Messages","description":"Messages inside a conversation"},{"name":"Calls","description":"Outbound voice calls initiated by an assistant"}],"servers":[{"url":"https://api.happ.tools"}],"components":{"securitySchemes":{"jwt-auth":{"scheme":"bearer","bearerFormat":"JWT","type":"http","name":"JWT Token","description":"Enter JWT token from admin panel"},"access-token":{"type":"apiKey","in":"header","name":"X-Access-Token","description":"Enter your Access Token (format: happ_...)"}},"schemas":{"CreateCompanyDto":{"type":"object","properties":{"name":{"type":"string","description":"Company name (2..100 chars)","example":"Acme Corp"},"description":{"type":"string","description":"Free-form company description (up to 1000 chars)","example":"Online furniture store, EU market"}},"required":["name"]},"UpdateCompanyDto":{"type":"object","properties":{"name":{"type":"string","description":"Company name (2..100 chars)","example":"Acme Corp"},"description":{"type":"string","description":"Free-form company description (up to 1000 chars)","example":"Online furniture store, EU market"}}},"CompanyUserPermissionInputDto":{"type":"object","properties":{"accessLevel":{"type":"string","enum":["read","write"]},"scopeType":{"type":"string","enum":["product","assistant","company_integration"]},"productKey":{"type":"string","description":"Required when scopeType=product"},"assistantId":{"type":"string","description":"Required when scopeType=assistant","format":"uuid"},"companyIntegrationId":{"type":"string","description":"Required when scopeType=company_integration","format":"uuid"}},"required":["accessLevel","scopeType"]},"SendInvitationDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address to send the invitation to","example":"teammate@example.com"},"role":{"type":"string","enum":["owner","admin","member"],"description":"Company role granted to the invitee. Defaults to member.","example":"member"},"permissions":{"description":"Granular permissions applied to the invitee after they accept the invitation","type":"array","items":{"$ref":"#/components/schemas/CompanyUserPermissionInputDto"}}},"required":["email"]},"AcceptInvitationDto":{"type":"object","properties":{"token":{"type":"string","description":"Invitation token from the invitation email link","example":"8f14e45fceea167a5a36dedd4bea2543"}},"required":["token"]},"CreateAccessTokenDto":{"type":"object","properties":{"name":{"type":"string","description":"Name for identifying the token","example":"Zapier integration"},"description":{"type":"string","description":"Description of the token usage","example":"Used by the Zapier workflow that syncs new leads"}}},"UpdateAccessTokenDto":{"type":"object","properties":{"name":{"type":"string","description":"Name for identifying the token","example":"Zapier integration"}}},"ReplaceCompanyUserPermissionsDto":{"type":"object","properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/CompanyUserPermissionInputDto"}}},"required":["permissions"]},"CommitVersionDto":{"type":"object","properties":{"message":{"type":"string","description":"Commit message — что сделано в этой версии"},"label":{"type":"string","description":"Короткая метка версии"}},"required":["message"]},"CreateVariantDto":{"type":"object","properties":{"name":{"type":"string","description":"Имя черновика (например, Dev)"},"fromVersionId":{"type":"string","format":"uuid","description":"Создать черновик из этой версии (иначе — из текущего состояния)"}},"required":["name"]},"PromoteVariantDto":{"type":"object","properties":{"message":{"type":"string","description":"Commit message мержа"}}},"CreateVaRegistrationDto":{"type":"object","properties":{"providerType":{"type":"string","enum":["elevenlabs","gemini","openai","deepgram","xai"]},"voiceLlmModelId":{"type":"string"},"textLlmModelId":{"type":"string"},"companyIntegrationId":{"type":"string","format":"uuid"},"providerConfig":{"type":"object"}},"required":["providerType"]},"CreateAssistantNewDto":{"type":"object","properties":{"name":{"type":"string"},"companyId":{"type":"string","format":"uuid"},"firstMessage":{"type":"string"},"promptText":{"type":"string"},"language":{"type":"string"},"timezone":{"type":"string","example":"Europe/Kyiv","description":"IANA timezone the agent reasons in"},"folderId":{"type":"string","format":"uuid"},"assistantOutputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"]},"userInputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"]},"eagerness":{"type":"string","enum":["eager","normal","patient"]},"isDefault":{"type":"boolean"},"softTimeout":{"type":"number"},"softTimeoutMessage":{"type":"string"},"streamingLatency":{"type":"number"},"turnAfterSilence":{"type":"number"},"silenceEndCallTimeout":{"type":"number"},"aiAutoReturnDelayMinutes":{"type":"number"},"contextHistoryRatio":{"type":"object","description":"Share of the model context window reserved for the verbatim dialog history (0.05-0.9). Null = platform default. Lower values cost less per reply but fold older turns into the running summary sooner.","minimum":0.05,"maximum":0.9},"disableAiOnOwnerReply":{"type":"boolean"},"disableFirstMessageInterruption":{"type":"boolean"},"vaRegistration":{"$ref":"#/components/schemas/CreateVaRegistrationDto"}},"required":["name","companyId","vaRegistration"]},"UpdateVaRegistrationDto":{"type":"object","properties":{"providerType":{"type":"string","enum":["elevenlabs","gemini","openai","deepgram","xai"]},"providerId":{"type":"string","format":"uuid","nullable":true},"voiceLlmModelId":{"type":"string","nullable":true},"textLlmModelId":{"type":"string"},"companyIntegrationId":{"type":"string","format":"uuid","nullable":true},"providerConfig":{"type":"object"}}},"UpdateAssistantNewDto":{"type":"object","properties":{"name":{"type":"string"},"firstMessage":{"type":"string"},"promptText":{"type":"string"},"language":{"type":"string"},"timezone":{"type":"string","example":"Europe/Kyiv","description":"IANA timezone the agent reasons in"},"disableFirstMessageInterruption":{"type":"boolean"},"eagerness":{"type":"string","enum":["eager","normal","patient"]},"softTimeout":{"type":"number","description":"-1 = disabled"},"softTimeoutMessage":{"type":"string"},"streamingLatency":{"type":"number","description":"0–4"},"turnAfterSilence":{"type":"number","description":"-1 = disabled"},"silenceEndCallTimeout":{"type":"number","description":"-1 = disabled"},"aiAutoReturnDelayMinutes":{"type":"number","description":"-1 = disabled"},"contextHistoryRatio":{"type":"object","description":"Share of the model context window reserved for the verbatim dialog history (0.05-0.9). Null = platform default. Lower values cost less per reply but fold older turns into the running summary sooner.","minimum":0.05,"maximum":0.9},"disableAiOnOwnerReply":{"type":"boolean","description":"When true, an outgoing message from the chat owner does NOT switch the chat into manual mode (AI keeps running). Default false preserves the existing takeover behavior."},"activeLlmAssistantIntegrationId":{"type":"string","format":"uuid","nullable":true},"draftTextLlmModelId":{"type":"string","format":"uuid","nullable":true},"vaRegistration":{"$ref":"#/components/schemas/UpdateVaRegistrationDto"}}},"CopyAssistantNewDto":{"type":"object","properties":{"vaRegistration":{"$ref":"#/components/schemas/UpdateVaRegistrationDto"}}},"CreateAssistantFolderNewDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string","description":"Hex color, defaults to #6366f1"},"companyId":{"type":"string","format":"uuid"}},"required":["name","companyId"]},"MoveAssistantToFolderNewDto":{"type":"object","properties":{"assistantId":{"type":"string","format":"uuid"},"folderId":{"type":"string","format":"uuid","nullable":true}},"required":["assistantId"]},"AddAssistantsToFolderNewDto":{"type":"object","properties":{"assistantIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["assistantIds"]},"RemoveAssistantsFromFolderNewDto":{"type":"object","properties":{"assistantIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["assistantIds"]},"UpdateAssistantFolderNewDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"}}},"ParameterDto":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name as passed to the tool","example":"customerName"},"type":{"type":"string","enum":["string","number","boolean","array","object"],"description":"Parameter data type","example":"string"},"isRequired":{"type":"boolean","description":"Whether the parameter is required for the tool call","example":true},"value_type":{"type":"string","enum":["llm_prompt","constant","dynamic_variable"],"description":"How the value is resolved: llm_prompt — extracted by the LLM, constant — fixed value, dynamic_variable — taken from call variables","example":"llm_prompt"},"description":{"type":"string","description":"Explanation of the parameter for the LLM","example":"Name of the customer"},"constant_value":{"type":"object","description":"Fixed value used when value_type is constant","example":"en"},"dynamic_variable":{"type":"string","description":"Name of the dynamic variable used when value_type is dynamic_variable","example":"customer_name"},"dynamic_variable_value":{"type":"string","description":"Fallback value for the dynamic variable when it is not set","example":"Guest"},"items":{"description":"Schema of array items when type is array","allOf":[{"$ref":"#/components/schemas/ParameterDto"}]},"properties":{"description":"Nested object properties when type is object","type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}}},"required":["name","type","isRequired"]},"CreateAssistantToolNewDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["webhook_init","webhook_action","webhook_postcall","webhook_client","system"],"default":"webhook_action"},"apiCallUrl":{"type":"string"},"httpMethod":{"type":"string","enum":["get","post","put","delete","patch"]},"executionMode":{"type":"string","enum":["immediate","post_tool_speech","async"],"default":"immediate"},"disableInterruptions":{"type":"boolean","default":false},"disabled":{"type":"boolean","default":false},"webhookSecret":{"type":"string"},"toolCallSound":{"type":"string","enum":["elevator1","elevator2","elevator3","elevator4","typing"]},"params":{"type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}},"assistantId":{"type":"string","format":"uuid"}},"required":["name","assistantId"]},"UpdateAssistantToolNewDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["webhook_init","webhook_action","webhook_postcall","webhook_client","system"]},"apiCallUrl":{"type":"string"},"httpMethod":{"type":"string","enum":["get","post","put","delete","patch"]},"executionMode":{"type":"string","enum":["immediate","post_tool_speech","async"]},"disableInterruptions":{"type":"boolean"},"disabled":{"type":"boolean"},"webhookSecret":{"type":"string"},"toolCallSound":{"type":"string","enum":["elevator1","elevator2","elevator3","elevator4","typing"]},"params":{"type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}}}},"AttachPhoneNewDto":{"type":"object","properties":{"phoneId":{"type":"string","format":"uuid"},"assistantId":{"type":"string","format":"uuid"}},"required":["phoneId","assistantId"]},"DetachPhoneNewDto":{"type":"object","properties":{"phoneId":{"type":"string","format":"uuid"}},"required":["phoneId"]},"CreateAssistantPhoneNewDto":{"type":"object","properties":{"companyId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"sipLogin":{"type":"string"},"password":{"type":"string"},"telephonyUrl":{"type":"string","maxLength":64},"authProxy":{"type":"string","nullable":true},"authUsername":{"type":"string","nullable":true},"comment":{"type":"string"},"codec":{"type":"string","enum":["alaw","ulaw"],"default":"alaw"}},"required":["companyId"]},"UpdateAssistantPhoneNewDto":{"type":"object","properties":{"phoneNumber":{"type":"string"},"sipLogin":{"type":"string"},"password":{"type":"string"},"telephonyUrl":{"type":"string","maxLength":64},"authProxy":{"type":"string","nullable":true},"authUsername":{"type":"string","nullable":true},"comment":{"type":"string"},"codec":{"type":"string","enum":["alaw","ulaw"]}}},"CreateAssistantKnowledgeNewDto":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["url","text","file"]},"resourceUrl":{"type":"string"},"resourceDescription":{"type":"string"},"resourceContent":{"type":"string"},"fileId":{"type":"string","description":"File id (its text is extracted into resource_content)"},"isVector":{"type":"boolean","default":false},"chunkingStrategy":{"type":"string","enum":["tokens","items"],"default":"tokens"},"itemDelimiter":{"type":"string"},"extraChunkPayloads":{"type":"array","items":{"type":"object","additionalProperties":true}},"assistantId":{"type":"string","format":"uuid"}},"required":["name","type","assistantId"]},"UpdateAssistantKnowledgeNewDto":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["url","text","file"]},"resourceUrl":{"type":"string"},"resourceDescription":{"type":"string"},"resourceContent":{"type":"string"},"fileId":{"type":"string"},"isVector":{"type":"boolean"},"chunkingStrategy":{"type":"string","enum":["tokens","items"]},"itemDelimiter":{"type":"string"},"extraChunkPayloads":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"CreateToolForTemplateNewDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["webhook_init","webhook_action","webhook_postcall","webhook_client","system"]},"apiCallUrl":{"type":"string"},"httpMethod":{"type":"string","enum":["get","post","put","delete","patch"]},"executionMode":{"type":"string","enum":["immediate","post_tool_speech","async"]},"disableInterruptions":{"type":"boolean"},"webhookSecret":{"type":"string"},"toolCallSound":{"type":"string","enum":["elevator1","elevator2","elevator3","elevator4","typing"]},"params":{"type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}}},"required":["name"]},"CreateKnowledgeForTemplateNewDto":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["url","text","file"]},"resourceUrl":{"type":"string"},"resourceDescription":{"type":"string"},"resourceContent":{"type":"string"},"fileId":{"type":"string"},"isVector":{"type":"boolean"},"chunkingStrategy":{"type":"string","enum":["tokens","items"]},"itemDelimiter":{"type":"string"}},"required":["name","type"]},"CreateAssistantTemplateNewDto":{"type":"object","properties":{"assistant":{"$ref":"#/components/schemas/CreateAssistantNewDto"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/CreateToolForTemplateNewDto"}},"knowledges":{"type":"array","items":{"$ref":"#/components/schemas/CreateKnowledgeForTemplateNewDto"}}},"required":["assistant"]},"UpdateAssistantTemplateNewDto":{"type":"object","properties":{"assistant":{"$ref":"#/components/schemas/UpdateAssistantNewDto"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/CreateToolForTemplateNewDto"}},"knowledges":{"type":"array","items":{"$ref":"#/components/schemas/CreateKnowledgeForTemplateNewDto"}}},"required":["assistant"]},"CreateAssistantIntegrationNewDto":{"type":"object","properties":{"assistantId":{"type":"string","format":"uuid"},"companyIntegrationId":{"type":"string","format":"uuid"},"settings":{"type":"object"}},"required":["assistantId","companyIntegrationId"]},"UpdateAssistantIntegrationNewDto":{"type":"object","properties":{"settings":{"type":"object"}}},"VaCallbackDto":{"type":"object","properties":{"registrationId":{"type":"string","format":"uuid","description":"Our registration id this callback is about."},"status":{"type":"string","enum":["synced","failed","deprovisioned","deprovision_failed"]},"vaAssistantId":{"type":"string","description":"VA handle; required when status = synced."},"syncedVersion":{"type":"number","description":"desired_version VA converged to; required when status = synced."},"vaRegistrationId":{"type":"string","description":"VA's own registration id; stored when present on a synced callback."},"vaAgentId":{"type":"string","description":"VA's agent id; stored when present on a synced callback."},"vaSipId":{"type":"string","description":"VA SIP id; stored on the assistant's phone when present on a synced callback."},"error":{"type":"string","description":"Failure detail when status = failed."}},"required":["registrationId","status"]},"StartVoiceTestSessionDto":{"type":"object","properties":{"vaVersion":{"type":"number"},"dynamicVariables":{"type":"object","additionalProperties":{"type":"string"},"example":{"customer_name":"Іван","order_id":"ORD-12345"}}}},"CreateAssistantDto":{"type":"object","properties":{"name":{"type":"string","description":"Assistant display name","example":"Sales Assistant"},"firstMessage":{"type":"string","description":"Greeting the assistant sends when a conversation starts","example":"Hi! How can I help you today?"},"promptText":{"type":"string","description":"System prompt defining the assistant behavior and knowledge","example":"You are a helpful sales assistant for Acme Corp. Answer questions about our products."},"companyId":{"type":"string","format":"uuid","description":"ID of the company the assistant belongs to","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"providerId":{"type":"string","description":"Provider ID for voice assistant integration","format":"uuid"},"language":{"type":"string","description":"Primary conversation language of the assistant","example":"en"},"assistantOutputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"],"description":"Audio format of the assistant voice output"},"userInputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"],"description":"Audio format expected for user voice input"},"textLlmModelId":{"type":"string","description":"FK to llm_models (type=text) — chat LLM selection","format":"uuid"},"voiceLlmModelId":{"type":"string","description":"FK to llm_models (type=voice) — voice agent LLM selection","format":"uuid"},"disableFirstMessageInterruption":{"type":"boolean","description":"Disable interruption of the first message"},"ttsModel":{"type":"string","description":"Text-to-speech model identifier","example":"eleven_turbo_v2_5"},"voiceAssistantId":{"type":"string","description":"External voice assistant ID at the voice provider","example":"va_9f8e7d6c5b4a"},"elevenLabsVoiceId":{"type":"string","description":"ElevenLabs voice ID used for speech synthesis","example":"21m00Tcm4TlvDq8ikWAM"},"vaVoice":{"type":"string","description":"Voice name used by the voice assistant","example":"alloy"},"eagerness":{"type":"string","enum":["eager","normal","patient"],"default":"normal","description":"How eagerly the voice agent takes its conversational turn"},"softTimeout":{"type":"number","default":-1,"description":"Seconds of user silence before the soft-timeout message is spoken. A value of -1 disables it."},"softTimeoutMessage":{"type":"string","description":"Message the assistant speaks when the soft timeout fires","example":"Are you still there?"},"streamingLatency":{"type":"number","default":2,"minimum":0,"maximum":4,"description":"Streaming latency optimization (0-4)"},"turnAfterSilence":{"type":"number","default":7,"minimum":-1,"maximum":300,"description":"The maximum number of seconds since the user last spoke. If exceeded, the agent will respond and force a turn. A value of -1 means the agent will wait indefinitely for user input."},"silenceEndCallTimeout":{"type":"number","default":-1,"minimum":-1,"maximum":7200,"description":"Seconds of silence after which the call ends automatically. A value of -1 disables this. Maximum 2 hours (7200 seconds)."}},"required":["name","promptText","companyId"]},"UpdateAssistantBodyDto":{"type":"object","properties":{"name":{"type":"string","description":"Assistant display name","example":"Sales Assistant"},"firstMessage":{"type":"string","description":"Greeting the assistant sends when a conversation starts","example":"Hi! How can I help you today?"},"promptText":{"type":"string","description":"System prompt defining the assistant behavior and knowledge","example":"You are a helpful sales assistant for Acme Corp. Answer questions about our products."},"type":{"type":"string","enum":["BLANK","MEDICAL","RESTAURANT"],"description":"Assistant type"},"language":{"type":"string","description":"Primary conversation language of the assistant","example":"en"},"assistantOutputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"],"description":"Audio format of the assistant voice output"},"userInputAudioFormat":{"type":"string","enum":["pcm_8000","pcm_16000","pcm_22050","pcm_24000","pcm_44100","pcm_48000","ulaw_8000"],"description":"Audio format expected for user voice input"},"textLlmModelId":{"type":"string","description":"FK to llm_models (type=text) — chat LLM selection","format":"uuid"},"voiceLlmModelId":{"type":"string","description":"FK to llm_models (type=voice) — voice agent LLM selection","format":"uuid"},"disableFirstMessageInterruption":{"type":"boolean","description":"Disable interruption of the first message"},"voiceAssistantId":{"type":"string","description":"External voice assistant ID at the voice provider","example":"va_9f8e7d6c5b4a"},"elevenLabsVoiceId":{"type":"string","description":"ElevenLabs voice ID used for speech synthesis","example":"21m00Tcm4TlvDq8ikWAM"},"elevenLabsAssistantId":{"type":"string","description":"ElevenLabs agent ID linked to this assistant","example":"agent_01jz8x2y3v4w5t6u7r8s9q0p1o"},"vaVoice":{"type":"string","description":"Voice name used by the voice assistant","example":"alloy"},"ttsModel":{"type":"string","description":"Text-to-speech model identifier","example":"eleven_turbo_v2_5"},"eagerness":{"type":"string","enum":["eager","normal","patient"],"default":"normal","description":"How eagerly the voice agent takes its conversational turn"},"softTimeout":{"type":"number","default":-1,"description":"Seconds of user silence before the soft-timeout message is spoken. A value of -1 disables it."},"softTimeoutMessage":{"type":"string","description":"Message the assistant speaks when the soft timeout fires","example":"Are you still there?"},"streamingLatency":{"type":"number","default":2,"minimum":0,"maximum":4,"description":"Streaming latency optimization (0-4)"},"turnAfterSilence":{"type":"number","default":7,"minimum":-1,"maximum":300,"description":"The maximum number of seconds since the user last spoke. If exceeded, the agent will respond and force a turn. A value of -1 means the agent will wait indefinitely for user input."},"silenceEndCallTimeout":{"type":"number","default":-1,"minimum":-1,"maximum":7200,"description":"Seconds of silence after which the call ends automatically. A value of -1 disables this. Maximum 2 hours (7200 seconds)."},"aiAutoReturnDelayMinutes":{"type":"number","default":30,"minimum":-1,"maximum":1440,"description":"Minutes of silence before the AI assistant auto-returns to the chat after a manager takeover. A value of -1 disables auto-return (the AI never rejoins on its own). Maximum 24 hours (1440 minutes)."}}},"CopyAssistantDto":{"type":"object","properties":{"providerId":{"type":"string","description":"Provider ID to attach the copied assistant to; defaults to the source assistant provider","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}},"OriginateCallDto":{"type":"object","properties":{"phoneNumber":{"type":"string","description":"Phone number to originate call to. Accepts +<digits>, plain digits with country code (e.g. 380...), or local format starting with 0.","example":"+380501234567"},"callerAssistantId":{"type":"string","description":"ID of the assistant to make the call as. Must belong to the same company as the assistant on the route. If omitted, the route assistant is used.","example":"00000000-0000-0000-0000-000000000000"},"dynamicVariables":{"type":"object","description":"Arbitrary key/value pairs forwarded to the voice assistant as `dynamic_variables`. Used to personalize the conversation (customer name, order id, preferred language, etc.).","additionalProperties":true,"example":{"customer_name":"John Doe","order_id":"ORD-12345","preferred_language":"en"}}},"required":["phoneNumber"]},"AttachPhoneToAssistantDto":{"type":"object","properties":{}},"DetachPhoneFromAssistantDto":{"type":"object","properties":{}},"CreateAssistantToolsDto":{"type":"object","properties":{"name":{"type":"string","description":"Tool (function) name the LLM calls; use snake_case","example":"create_order"},"disableInterruptions":{"type":"boolean","default":false,"description":"If true, tool execution will disable interruptions"},"type":{"type":"string","enum":["webhook_init","webhook_action","webhook_postcall","webhook_client","system"],"default":"webhook_action","description":"How the tool is executed"},"apiCallUrl":{"type":"string","description":"Required for webhook types (webhook_action, webhook_postcall), not needed for client type","example":"https://example.com/webhooks/create-order"},"description":{"type":"string","description":"Explanation of what the tool does and when the LLM should call it","example":"Creates a new order in the CRM when the customer confirms the purchase"},"httpMethod":{"type":"string","enum":["get","post","put","delete","patch"],"default":"POST","description":"HTTP method for webhook types (webhook_action, webhook_postcall), not needed for client type"},"executionMode":{"type":"string","enum":["immediate","post_tool_speech","async"],"default":"immediate","description":"Execution mode: immediate - execute immediately, post_tool_speech - execute after speech, async - execute asynchronously"},"parameters":{"type":"object","description":"JSON Schema for function parameters"},"webhookSecret":{"type":"string","description":"Webhook secret for webhook_init tools","example":"whsec_9f8e7d6c5b4a3210"},"toolCallSound":{"type":"string","enum":["elevator1","elevator2","elevator3","elevator4","typing"],"description":"Sound file to play when tool is called"},"params":{"description":"Structured parameter definitions the LLM fills when calling the tool","example":[{"name":"customerName","type":"string","description":"Name of the customer","isRequired":true}],"type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}},"assistantId":{"type":"string","format":"uuid","description":"ID of the assistant the tool belongs to","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["name","assistantId"]},"UpdateAssistantToolsDto":{"type":"object","properties":{"name":{"type":"string","description":"Tool (function) name the LLM calls; use snake_case","example":"create_order"},"disableInterruptions":{"type":"boolean","default":false,"description":"If true, tool execution will disable interruptions"},"type":{"type":"string","enum":["webhook_init","webhook_action","webhook_postcall","webhook_client","system"],"description":"How the tool is executed"},"apiCallUrl":{"type":"string","description":"Required for webhook type, not needed for client type","example":"https://example.com/webhooks/create-order"},"description":{"type":"string","description":"Explanation of what the tool does and when the LLM should call it","example":"Creates a new order in the CRM when the customer confirms the purchase"},"httpMethod":{"type":"string","enum":["get","post","put","delete","patch"],"description":"HTTP method for webhook type, not needed for client type"},"executionMode":{"type":"string","enum":["immediate","post_tool_speech","async"],"description":"Execution mode: immediate - execute immediately, post_tool_speech - execute after speech, async - execute asynchronously"},"parameters":{"type":"object","description":"JSON Schema for function parameters"},"webhookSecret":{"type":"string","description":"Webhook secret for webhook_init tools","example":"whsec_9f8e7d6c5b4a3210"},"toolCallSound":{"type":"string","enum":["elevator1","elevator2","elevator3","elevator4","typing"],"description":"Sound file to play when tool is called"},"elevenLabsToolId":{"type":"string","description":"ElevenLabs tool ID for integration","example":"tool_01jz8x2y3v4w5t6u7r8s9q0p1o"},"params":{"description":"Structured parameter definitions the LLM fills when calling the tool","example":[{"name":"customerName","type":"string","description":"Name of the customer","isRequired":true}],"type":"array","items":{"$ref":"#/components/schemas/ParameterDto"}}}},"CreateAssistantFolderDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the folder","example":"Customer Support Assistants","maxLength":255},"description":{"type":"string","description":"Description of the folder","example":"Assistants dedicated to handling customer support inquiries"},"color":{"type":"string","description":"Hex color for the folder","example":"#6366f1","default":"#6366f1"},"companyId":{"type":"string","description":"Company ID that owns the folder","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["name","companyId"]},"AddAssistantsToFolderDto":{"type":"object","properties":{"assistantIds":{"description":"Array of assistant IDs to add to the folder","example":["123e4567-e89b-12d3-a456-426614174000","987f6543-d21c-34b5-a678-123456789012"],"type":"array","items":{"type":"string"}}},"required":["assistantIds"]},"RemoveAssistantsFromFolderDto":{"type":"object","properties":{"assistantIds":{"description":"Array of assistant IDs to remove from the folder","example":["123e4567-e89b-12d3-a456-426614174000"],"type":"array","items":{"type":"string"}}},"required":["assistantIds"]},"MoveAssistantToFolderDto":{"type":"object","properties":{"assistantId":{"type":"string","description":"Assistant ID to move","example":"123e4567-e89b-12d3-a456-426614174000"},"folderId":{"type":"string","description":"Target folder ID (null to remove from folder)","example":"987f6543-d21c-34b5-a678-123456789012"}},"required":["assistantId"]},"CreateAssistantTemplateDto":{"type":"object","properties":{"assistant":{"description":"Assistant creation data","allOf":[{"$ref":"#/components/schemas/CreateAssistantDto"}]},"tools":{"description":"Array of tools to create for the assistant","items":{"type":"array","items":{"type":"createToolForTemplateDto"}},"type":"array"},"knowledges":{"description":"Array of knowledge bases to create for the assistant","items":{"type":"array","items":{"type":"createKnowledgeForTemplateDto"}},"type":"array"}},"required":["assistant","tools","knowledges"]},"UpdateAssistantTemplateDto":{"type":"object","properties":{"assistant":{"description":"Assistant update data","allOf":[{"$ref":"#/components/schemas/UpdateAssistantBodyDto"}]},"tools":{"description":"Array of tools to create for the assistant","items":{"type":"array","items":{"type":"createToolForTemplateDto"}},"type":"array"},"knowledges":{"description":"Array of knowledge bases to create for the assistant","items":{"type":"array","items":{"type":"createKnowledgeForTemplateDto"}},"type":"array"}},"required":["assistant","tools","knowledges"]},"CreateAssistantKnowledgeDto":{"type":"object","properties":{"name":{"type":"string","description":"Knowledge item name","example":"Product FAQ"},"type":{"type":"string","enum":["url","text","file"],"description":"Type of knowledge base content"},"resourceUrl":{"type":"string","description":"Resource URL (required when type is url)","example":"https://example.com/faq"},"resourceDescription":{"type":"string","description":"Short summary of the resource shown to the LLM when selecting knowledge","example":"Answers to common questions about delivery and returns"},"resourceContent":{"type":"string","description":"Inline text content of the knowledge item (used when type is text)","example":"Delivery takes 2-3 business days. Returns are accepted within 14 days."},"assistantId":{"type":"string","format":"uuid","description":"ID of the assistant the knowledge item belongs to","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"fileId":{"type":"string","description":"File ID to associate with knowledge base"},"vectorIds":{"description":"Array of vector IDs for knowledge base","type":"array","items":{"type":"string"}},"isVector":{"type":"boolean","default":false,"description":"Whether this knowledge is vector-based"},"chunkingStrategy":{"type":"string","enum":["tokens","items"],"default":"tokens","description":"How the content is split into chunks for vector indexing"},"itemDelimiter":{"type":"string","description":"Delimiter string that separates items when chunking by delimiter","example":"---"},"isSystem":{"type":"boolean","default":false,"description":"Whether this is a system-managed knowledge base"}},"required":["name","type","assistantId","isVector","chunkingStrategy","isSystem"]},"UpdateAssistantKnowledgeDto":{"type":"object","properties":{"name":{"type":"string","description":"Knowledge item name","example":"Product FAQ"},"type":{"type":"string","enum":["url","text","file"],"description":"Type of knowledge content"},"resourceUrl":{"type":"string","description":"Resource URL (required when type is url)","example":"https://example.com/faq"},"resourceDescription":{"type":"string","description":"Short summary of the resource shown to the LLM when selecting knowledge","example":"Answers to common questions about delivery and returns"},"resourceContent":{"type":"string","description":"Inline text content of the knowledge item (used when type is text)","example":"Delivery takes 2-3 business days. Returns are accepted within 14 days."},"elevenLabsKnowledgeId":{"type":"string","description":"ElevenLabs knowledge base ID for integration","example":"kb_01jz8x2y3v4w5t6u7r8s9q0p1o"},"fileId":{"type":"string","description":"File ID to associate with knowledge base"},"vectorIds":{"description":"Array of vector IDs for knowledge base","type":"array","items":{"type":"string"}},"isVector":{"type":"boolean","description":"Whether this knowledge is vector-based"},"chunkingStrategy":{"type":"string","enum":["tokens","items"],"description":"How the content is split into chunks for vector indexing"},"itemDelimiter":{"type":"string","description":"Delimiter string that separates items when chunking by delimiter","example":"---"}}},"CreateChatDto":{"type":"object","properties":{"companyId":{"type":"string","description":"ID of the company the chat belongs to","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"assistantId":{"type":"string","description":"ID of the assistant handling the chat","format":"uuid","example":"b2c3d4e5-f6a7-8901-bcde-f23456789012"},"messenger":{"type":"string","enum":["instagram","telegram","telegram-bot","messenger","whatsapp","whatsapp-business","viber-echat","custom-messenger","widget","prom","rozetka","olx","playground"],"description":"Messenger channel the chat runs on","example":"telegram"},"telegramId":{"type":"string","description":"Telegram user ID of the chat counterpart","example":"123456789"},"instagramId":{"type":"string","description":"Instagram user ID of the chat counterpart","example":"17841400000000000"},"fromName":{"type":"string","description":"Display name of the message sender","example":"John Doe"},"fromId":{"type":"string","description":"Messenger-specific ID of the message sender","example":"123456789"},"toName":{"type":"string","description":"Display name of the message recipient","example":"Acme Support Bot"},"toId":{"type":"string","description":"Messenger-specific ID of the message recipient","example":"987654321"},"displayName":{"type":"string","description":"Human-readable chat name shown in the inbox","example":"John Doe"},"externalId":{"type":"string","description":"External chat ID in the source messenger or integration","example":"chat-42-external"}},"required":["companyId","messenger"]},"UpdateChatDto":{"type":"object","properties":{"assistantId":{"type":"string","description":"ID of the assistant handling the chat","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"isUnderAiControl":{"type":"boolean","description":"Whether the AI assistant responds in this chat; false hands the chat over to a human","example":true},"displayName":{"type":"string","description":"Human-readable chat name shown in the inbox","example":"John Doe"}}},"SuggestAiReplyDto":{"type":"object","properties":{}},"ToggleAiControlDto":{"type":"object","properties":{"isUnderAiControl":{"type":"boolean","description":"Target AI control state for the chat. `true` enables AI handling, `false` disables it.","example":false},"aiDisableReason":{"type":"string","description":"Reason for disabling AI. Applied only when `isUnderAiControl` is `false`. Defaults to `manual` when omitted while disabling.","enum":["manual","auto","insufficient_balance"],"example":"manual","nullable":true}},"required":["isUnderAiControl"]},"AssignAssistantDto":{"type":"object","properties":{"assistantId":{"type":"string","description":"ID of the assistant to assign to the chat","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["assistantId"]},"CreateMessageDto":{"type":"object","properties":{"source":{"type":"string","enum":["TELEGRAM","TELEGRAM_BOT","INSTAGRAM","WHATSAPP","MESSENGER","ECHAT","CUSTOM_MESSENGER","WIDGET","PROM","ROZETKA","OLX","PLATFORM","MOBILE","API","AI","PLAYGROUND"],"description":"Message source"},"role":{"type":"string","enum":["System","Assistant","User","Developer"],"description":"Message role"},"type":{"type":"string","enum":["Text","Audio","File","Document","Photo","Video","Specific","FunctionCallOutput","FunctionCall"],"description":"Message type"},"specificType":{"type":"string","enum":["telegram_location","telegram_live_location","telegram_contact","telegram_poll","telegram_dice","telegram_venue","telegram_game","telegram_invoice","telegram_story","telegram_giveaway","telegram_giveaway_results","telegram_paid_media","telegram_unsupported","instagram_story","instagram_reel","instagram_post","whatsapp_location","whatsapp_contact","whatsapp_poll","whatsapp_event"],"description":"Integration specific message type"},"externalId":{"type":"string","description":"External message ID"},"sessionId":{"type":"string","description":"Session ID"},"fromId":{"type":"string","description":"Sender ID"},"toId":{"type":"string","description":"Recipient ID"},"chatId":{"type":"string","description":"Chat ID"},"sendAsAccountId":{"type":"string","description":"Group chats: send through this connected account (its messenger id) instead of the chat's own. Must be a member of the group."},"text":{"type":"string","description":"Message text content"},"transcription":{"type":"string","description":"Audio transcription"},"audioUrl":{"type":"string","description":"Audio file URL"},"fileUrl":{"type":"string","description":"File URL"},"functionCallId":{"type":"string","description":"Function call ID"},"functionCallName":{"type":"string","description":"Function call name"},"functionCallInput":{"type":"string","description":"Function call input"},"functionCallOutput":{"type":"string","description":"Function call output"},"mediaIds":{"description":"Media UUIDs to attach (max 10)","type":"array","items":{"type":"string"}}},"required":["source","role","type"]},"UpdateMessageDto":{"type":"object","properties":{"source":{"type":"string","enum":["TELEGRAM","TELEGRAM_BOT","INSTAGRAM","WHATSAPP","MESSENGER","ECHAT","CUSTOM_MESSENGER","WIDGET","PROM","ROZETKA","OLX","PLATFORM","MOBILE","API","AI","PLAYGROUND"],"description":"Message source"},"role":{"type":"string","enum":["System","Assistant","User","Developer"],"description":"Message role"},"type":{"type":"string","enum":["Text","Audio","File","Document","Photo","Video","Specific","FunctionCallOutput","FunctionCall"],"description":"Message type"},"specificType":{"type":"string","enum":["telegram_location","telegram_live_location","telegram_contact","telegram_poll","telegram_dice","telegram_venue","telegram_game","telegram_invoice","telegram_story","telegram_giveaway","telegram_giveaway_results","telegram_paid_media","telegram_unsupported","instagram_story","instagram_reel","instagram_post","whatsapp_location","whatsapp_contact","whatsapp_poll","whatsapp_event"],"description":"Integration specific message type"},"externalId":{"type":"string","description":"External message ID"},"sessionId":{"type":"string","description":"Session ID"},"fromId":{"type":"string","description":"Sender ID"},"toId":{"type":"string","description":"Recipient ID"},"chatId":{"type":"string","description":"Chat ID"},"text":{"type":"string","description":"Message text content"},"transcription":{"type":"string","description":"Audio transcription"},"audioUrl":{"type":"string","description":"Audio file URL"},"fileUrl":{"type":"string","description":"File URL"},"functionCallId":{"type":"string","description":"Function call ID"},"functionCallName":{"type":"string","description":"Function call name"},"functionCallInput":{"type":"string","description":"Function call input"},"functionCallOutput":{"type":"string","description":"Function call output"}}},"ChatCommentDto":{"type":"object","properties":{}},"UpdateChatMetaDto":{"type":"object","properties":{"labels":{"description":"Free-form labels attached to the chat","type":"array","items":{"type":"string"}},"comments":{"description":"Free-form manager comments on the chat","type":"array","items":{"$ref":"#/components/schemas/ChatCommentDto"}},"note":{"type":"string","description":"Free-form manager note about the client. Rendered on the mobile chat-profile screen («Нотатка» block)."}}},"AddChatLabelDto":{"type":"object","properties":{"label":{"type":"string","description":"Label text (1..64 chars)"}},"required":["label"]},"AddChatCommentDto":{"type":"object","properties":{"text":{"type":"string","description":"Comment body (1..2000 chars)"}},"required":["text"]},"CreateMemoryDto":{"type":"object","properties":{"content":{"type":"string","description":"Memory text the assistant remembers about this chat (up to 2000 chars)","example":"Customer prefers delivery after 6pm"}},"required":["content"]},"UpdateMemoryDto":{"type":"object","properties":{"content":{"type":"string","description":"Updated memory text (up to 2000 chars)","example":"Customer prefers delivery after 6pm"}}},"StartPlaygroundDto":{"type":"object","properties":{"assistantId":{"type":"string","description":"Assistant to test","format":"uuid"}},"required":["assistantId"]},"SendPlaygroundMessageDto":{"type":"object","properties":{"text":{"type":"string","description":"Message text","minLength":1,"maxLength":10000}},"required":["text"]},"TestToolDto":{"type":"object","properties":{"params":{"type":"object","description":"Params forwarded to the webhook as the request body"}}},"KnowledgeQueryDto":{"type":"object","properties":{"assistantId":{"type":"string","format":"uuid"},"query":{"type":"string","maxLength":2000},"topK":{"type":"number","minimum":1,"maximum":20}},"required":["assistantId","query"]},"SignupMetaDto":{"type":"object","properties":{"utm_source":{"type":"string","description":"UTM source the user signed up from","example":"google"},"utm_medium":{"type":"string","description":"UTM medium the user signed up from","example":"cpc"},"utm_campaign":{"type":"string","description":"UTM campaign the user signed up from","example":"spring_launch"},"utm_content":{"type":"string","description":"UTM content variant the user signed up from","example":"hero_banner"},"utm_term":{"type":"string","description":"UTM search term the user signed up from","example":"ai assistant"},"utm_page":{"type":"string","description":"Landing page the user signed up from","example":"/pricing"},"utm_referrer":{"type":"string","description":"Referrer URL captured at sign-up","example":"https://google.com/"},"fbclid":{"type":"string","description":"Meta click id, minted by the ad network for the click","example":"IwAR1x"},"gclid":{"type":"string","description":"Google Ads click id","example":"Cj0KCQjw"},"gbraid":{"type":"string","description":"Google's iOS replacement for gclid under ATT","example":"0AAAA"},"wbraid":{"type":"string","description":"Google's iOS replacement for gclid on web-to-app","example":"0AAAA"},"ttclid":{"type":"string","description":"TikTok click id","example":"E.C.P"},"msclkid":{"type":"string","description":"Microsoft Ads click id","example":"abc123"}}},"EmailAuthDto":{"type":"object","properties":{"email":{"type":"string","description":"User email address used as the login","example":"john.doe@example.com"},"password":{"type":"string","description":"Account password","example":"S3cure-passw0rd"},"inviteToken":{"type":"string","description":"Company invitation token; when provided, the new user joins the inviting company","example":"8f14e45fceea167a5a36dedd4bea2543"},"signupMeta":{"description":"Marketing attribution (UTM) captured at sign-up","allOf":[{"$ref":"#/components/schemas/SignupMetaDto"}]}},"required":["email","password"]},"PhoneAuthDto":{"type":"object","properties":{"tel":{"type":"string","description":"Phone number in international format; a verification code is sent to it via SMS","example":"+380501234567"},"signupMeta":{"description":"Marketing attribution (UTM) captured at sign-up","allOf":[{"$ref":"#/components/schemas/SignupMetaDto"}]}},"required":["tel"]},"AppleAuthDto":{"type":"object","properties":{"identityToken":{"type":"string","description":"Apple identity token (JWT) obtained from Sign in with Apple","example":"eyJraWQiOiJmaDZC..."},"nonce":{"type":"string","description":"Nonce used when requesting the Apple identity token, verified against the token claim","example":"c29tZS1yYW5kb20tbm9uY2U"},"firstName":{"type":"string","description":"User first name provided by Apple on the first sign-in only","example":"John"},"lastName":{"type":"string","description":"User last name provided by Apple on the first sign-in only","example":"Doe"},"inviteToken":{"type":"string","description":"Company invitation token; when provided, the new user joins the inviting company","example":"8f14e45fceea167a5a36dedd4bea2543"},"signupMeta":{"description":"Marketing attribution (UTM) captured at sign-up","allOf":[{"$ref":"#/components/schemas/SignupMetaDto"}]}},"required":["identityToken"]},"ForgotPasswordDto":{"type":"object","properties":{"email":{"type":"string","description":"Email of the account to send the password reset link to","example":"john.doe@example.com"}},"required":["email"]},"ResetPasswordDto":{"type":"object","properties":{"resetToken":{"type":"string","description":"Password reset token from the email link sent by the forgot-password endpoint","example":"9b1deb4d3b7d4bad9bdd2b0d7b3dcb6d"},"newPassword":{"type":"string","description":"New account password","example":"N3w-s3cure-passw0rd"}},"required":["resetToken","newPassword"]},"VerifyPhoneCodeDto":{"type":"object","properties":{"verificationCode":{"type":"string","description":"One-time verification code received via SMS","example":"482915"}},"required":["verificationCode"]},"DataDeletionRequestDto":{"type":"object","properties":{"signed_request":{"type":"string","description":"Meta signed_request payload sent by Facebook/Instagram for a user data deletion callback","example":"vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiJ9"}},"required":["signed_request"]}}}}