Company API

Every agent of the company with the messengers connected to it. The id is what you pass as agent_id elsewhere.

Creates a customer, or returns the existing one (upsert). Deduplication runs on the phone number in E.164 form, on the email, or on any messenger identity. An existing customer comes back with created:false and HTTP 200; a new one with created:true and HTTP 201.

At least one identifier is required: phone, email or a messenger. The placement block picks the pipeline and stage; it is NOT applied on the upsert branch — an existing customer is never relocated.

Two ways to register the customer with a photo in one call.

fetch_avatar: true — the simplest: SynQ pulls the photo from the messenger itself, using the agent's own bot credentials. You host nothing and move no bytes, and no Telegram file URL (which embeds a bot token) has to travel anywhere. Call it again later to refresh: an unchanged photo is not re-downloaded, a changed one is. Supported on Telegram, MAX and WhatsApp-personal. On WhatsApp Cloud, Instagram and Facebook the platform either exposes no customer photo or ties the profile read to an open 24-hour window — SynQ checks the window first and makes no call it should not make.

avatar_url — an http(s) link you host. Fetched once and stored; the link may expire afterwards.

Either way SynQ serves its own copy, so the response returns a /media/avatars/... path rather than your link. The two fields are mutually exclusive. A photo that cannot be fetched never fails the call: the customer is created and warnings[] says why it is missing, precisely — avatar_no_relationship (they have neither started the bot nor allowed it to write, so the profile is unreadable), avatar_no_photo (reachable, but no picture or privacy hides it), avatar_window_closed, avatar_channel_missing, avatar_unsupported, or avatar_download_failed. The first two are worth telling apart: one is fixed by the customer opening the bot, the other only by sending a picture of your own. On the upsert branch a new photo replaces the stored one; omitting both fields never wipes it.

Pass one of the sets: messenger_type together with messenger_id, or phone, or email.

The customer with its current pipeline stage and messenger identities.

Opens a dialog without messaging the customer. This is the server-side twin of the CRM's «operator writes first» button: the customer card gets a chat an operator can open and type into.

Idempotent by construction: an ACTIVE dialog for this (customer, agent) pair is returned as-is with created:false. No second dialog is opened and the timeline is not touched — calling again is safe.

A freshly created dialog gets one system message, «Conversation created via API». Without it the dialog has no last_message_at, and the operator's list — sorted by that field — pushes it to the very bottom, which reads as if it were never created.

Omit agent_id only when the customer already has a dialog or a deal to inherit the agent from. In a company with several agents, pass it explicitly.

Can you actually reach this customer? The response answers that without you asking: customer_blocked is true when they have blocked the bot. You send nothing about it — Telegram reports a block to SynQ and we keep the state, so this is our own knowledge, as fresh as the last thing the messenger told us. A newly created dialog also gets the fact stamped into its timeline, so an operator opening the chat sees the wall before typing into it; an existing dialog already carries its own block event and is not re-stamped on every call.

Telegram-only, by construction: it is the surface that reports the fact. On WhatsApp, Instagram and the rest a block stays invisible until a send fails, and probing for it would mean querying those APIs about people who never wrote to us — the traffic they punish.

Sending an operator straight there. The response carries crm_url — a deep link that opens this exact dialog in the CRM. Use it instead of assembling the address yourself: the CRM host differs between environments and has already moved once, and a link built from the marketing apex lands on a redirect stub rather than the chat. The id field is the conversation id if you need it on its own.

Every deal of the customer, closed ones (won/lost) included — this is how you check whether they have been through the pipeline before.

409 conflict means an active deal already exists in that pipeline: one active deal per pipeline is the rule.

One person can arrive twice: they take a promo code on Instagram and then talk to you on Telegram. For us that is two cards, and often the only thing tying them together is the code that was issued — so the donor card may be named by promo_code instead of from_customer_id.

The winner is the card in the path. Its own ids never change, which is why you should point the call at the card your integration already writes to. Messengers, conversations, deals, variables, issued codes, keyword hits and notes move onto it; fields already filled on the winner are never overwritten — only the gaps are taken from the donor. The donor is not deleted (its conversation history hangs off it), it is flagged as merged and deactivated.

Conversations. A conversation belongs to a (customer, agent) pair and does not distinguish messengers — every messenger of that agent writes into one thread, and each message carries its own source. So messages from a donor thread on the same agent are always merged into the surviving thread: two live threads on one agent would make sending pick between them, and archiving one would orphan its messages. Crossing to a different agent happens only with absorb_conversations: true, because that agent has its own prompt and its own pipeline. keep_conversation_id names which thread survives; by default it is the winner's.

Whatever could not be moved is reported in warnings rather than passed over in silence: a second code from the same pool stays with the donor (one code per customer per pool is enforced by the database, and the customer already holds it), a second active deal in the same pipeline is closed as a duplicate, and same-named variables stay with the winner.

Repeating the call is safe: an already merged donor returns already_merged: true and moves nothing — including when the donor is looked up by a code that now belongs to the winner.

Sends a message to a specific messenger of the customer. Free-form text needs the messages:send scope, a WhatsApp template needs messages:template — which one applies is decided by the request body.

Formatting: write Markdown, once, for every messenger. You do not adapt the text per platform — SynQ renders it on the way out, the same pipeline the AI agent's own replies go through.

Parsed: **bold**, *italic*, ***bold italic***, ~~strikethrough~~, `code` , and [label](https://example.com).

Not parsed, and delivered literally: _underscores_ and __double underscores__ (use * for italic, not _), bullet lists, tables, blockquotes, and # headings.

Keep the opening marker glued to the text. **Заголовок** is bold; ** Заголовок** — with a space after the asterisks — is not markup at all by the standard, and different renderers disagree about it. Same for the closing marker. Lists are fine as plain text — they simply arrive as the characters you typed.

What each messenger receives:

A practical consequence: keep the same text short and marker-light if it may go to several channels. What renders as bold on Telegram is just words on Instagram.

The 24-hour window: on WhatsApp, Instagram and Facebook, free-form text outside the window is forbidden by Meta's rules, so a template is required. The window is anchored to the last INBOUND message from the customer. Telegram has no such window, but a bot cannot write first to someone who never pressed Start — that call returns 409 no_peer.

The optional follow_up block schedules a reminder: «send now, and nudge in N minutes if the customer stays silent». Any reply from the customer cancels the reminder on its own; there is no separate cancel call.

Does sending pause the agent? Only if you ask. By default pause_agent is false and the AI keeps running — which is what a notification needs: you tell the customer something, they reply, and the agent handles it. Set pause_agent: true when a human is taking the dialog over from your side; that stops the agent exactly like the pause button in the CRM and leaves a pause card in the timeline saying it came from the API. The pause is applied only after the message is confirmed sent — stopping the agent on a message that never left would hand the dialog to someone who does not know they now own it.

This is deliberately independent of the agent's auto_pause_on_human setting. That one fires when a human replies inside the CRM; an API call cannot tell a notification from a person typing, so it asks you rather than guessing.

Each messenger identity together with its sending window: whether free-form text is allowed right now and when the window closes.

Pass exactly one of stage_id or stage_code. A stage outside the customer's pipeline returns 409 — membership is checked through the agent.

Every variable stored on the customer, with its type and — for multi-valued ones — the list of elements. The response — for both GET and PATCH — is every variable of the customer or deal: name, value, type, is_list, value_list, group_name, updated_at.

Variables are addressed by name — the id of a variable is not something a caller can know.

A value may be given in short form ({"visits": 12}) or in full form ({"visits": {"value": 12, "type": "number"}}), mixed freely in one request. Variables you do not mention are left untouched: this is a patch, not a replacement of the whole set. Up to 50 per call.

Types are the same vocabulary the agent's collection fields use: text, select, datetime, number, date, time, phone, email. Omit the type and an existing variable keeps its own, while a new one takes it from the JSON type — a JSON number becomes number, a string stays text. A quoted "12" therefore stays text: guessing the type from the contents would eventually turn the part number 00123 into 123. Values are canonicalised the same way the agent canonicalises what a customer answers, so 26.08.2026 is stored as 2026-08-26. A value that does not fit its type is rejected with 422 validation_error naming the variable.

The type is not decoration: it decides which operators the audience builder offers. A number stored as text gives no «greater than» condition.

Lists are set with mode: replace (default), append, remove. Pass an array, or append one element at a time — a caller sending today's promo code does not need to know the whole history. Append deduplicates and keeps the order. A list holds one type of element, named in type. Its value stays filled with a readable join («RENT-A1, RENT-A2»), so consumers that know nothing about lists keep reading a single field.

null in short form deletes the variable; {"value": null} clears the value and keeps the field.

The response — for both GET and PATCH — is every variable of the customer or deal: name, value, type, is_list, value_list, group_name, updated_at.

Marks the deal won or lost with an optional reason.

Every variable stored on the deal. Same shape as the customer endpoint. The response — for both GET and PATCH — is every variable of the customer or deal: name, value, type, is_list, value_list, group_name, updated_at.

Same contract as customer variables, applied to a deal.

Variables are addressed by name — the id of a variable is not something a caller can know.

A value may be given in short form ({"visits": 12}) or in full form ({"visits": {"value": 12, "type": "number"}}), mixed freely in one request. Variables you do not mention are left untouched: this is a patch, not a replacement of the whole set. Up to 50 per call.

Types are the same vocabulary the agent's collection fields use: text, select, datetime, number, date, time, phone, email. Omit the type and an existing variable keeps its own, while a new one takes it from the JSON type — a JSON number becomes number, a string stays text. A quoted "12" therefore stays text: guessing the type from the contents would eventually turn the part number 00123 into 123. Values are canonicalised the same way the agent canonicalises what a customer answers, so 26.08.2026 is stored as 2026-08-26. A value that does not fit its type is rejected with 422 validation_error naming the variable.

The type is not decoration: it decides which operators the audience builder offers. A number stored as text gives no «greater than» condition.

Lists are set with mode: replace (default), append, remove. Pass an array, or append one element at a time — a caller sending today's promo code does not need to know the whole history. Append deduplicates and keeps the order. A list holds one type of element, named in type. Its value stays filled with a readable join («RENT-A1, RENT-A2»), so consumers that know nothing about lists keep reading a single field.

null in short form deletes the variable; {"value": null} clears the value and keeps the field.

Optionally filtered by agent_id. Each stage carries a stage_code — the stable handle to use in placement and stage moves instead of a UUID.

Searches every pool of the company: you know the code, not which pool it came from.

This is the bridge between two systems. Your service identifies a person by its own key — usually a Telegram id — while the code may well have been handed out in another messenger. The response carries the customer together with all of their messengers, so you can decide what to do next: write a variable, or merge the two cards.

Codes are minted by your service and handed out by the agent, so «how many are left and when to top up» is asked from the same place the codes come from. remaining is counted from the actual rows rather than a running counter, and low_threshold comes back already computed, so your monitor fires at the same number our own alert does. exhausted_requests is how many customers asked for a code and found the pool empty — the price of the outage.

Optional agent_id narrows the list to one agent.

Totals, remaining codes, alert threshold and the keywords that hand out from this pool.

Only the fields you pass are changed; the rest are left alone. Counters are not settings and cannot be set here.

is_enabled: false is the fastest way to stop the giveaway altogether: a disabled pool issues nothing at all and the agent switches to exhausted_instruction immediately. The codes stay where they are — the same call turns it back on.

The issue history: which code went to whom and when. issued_only keeps only the handed-out ones, search matches part of a code — a customer writing «my code does not work» is looked up by exactly that.

Sending the same list twice is safe. Deduplication happens in two layers, both inside the loader: within the submitted list, and against what is already stored — the latter by a unique (pool_id, code) index with ON CONFLICT DO NOTHING, which is database physics rather than a check in code, so parallel uploads cannot duplicate either. A repeat returns accepted: 0 instead of doubling the pool, which is why no idempotency header is needed here.

Deduplication is per pool: the same code in another pool goes through, since pools are independent campaigns. New codes join the end of the queue — already loaded ones are handed out first. Up to 10 000 per call. The loader also clears the alert flags once the pool is back above its threshold; without that the second time it emptied would pass unnoticed.

The report comes back whole — without the split between accepted, repeats inside the file and codes already in the pool, someone who uploads a file twice believes they have twice as many codes.

Retire codes that no longer work on your side — a batch was cancelled, a campaign closed, a code leaked. Until now the loader could only add, so a pool kept handing out what was already dead on your side and the customer walked into «this promo code is not active».

A code that was never handed out simply leaves the queue. A code already in a customer's hands stops counting as their code: the next time they ask, the agent hands them a replacement instead of the dead one. Issuing is idempotent, so before this it would have returned the very same code again.

Rows are not deleted — they are the issue history a complaint is investigated against, and the code the customer holds does not disappear because we forgot it. Repeating the call is safe: codes already revoked come back under already_revoked instead of being revoked twice.

To undo, upload the codes again: a revoked code that was never handed out returns to the queue.

The agent's WhatsApp templates — a cached proxy to Meta's registry. A template's status is APPROVED, PENDING or REJECTED. Either messages:template or agents:read is enough.

The call does not clear Meta's moderation: the template is queued as PENDING and later becomes APPROVED or REJECTED.