Lifecycle Hooks

Lifecycle hooks send a signed HTTPS request from SynapsAI to your system at three moments of every conversation. Use them to open a ticket when a chat starts, follow up when a customer goes quiet, or push the AI summary and the qualified lead into your CRM when the conversation ends.

Plan

Lifecycle hooks are available on the Growth plan and above.

The three events

Event	type	When it is sent
Conversation started	conversation.started	The customer’s first message opens a new conversation.
Pause / Inactivity	conversation.idle	Nobody has written for the time you set (2 to 1439 minutes, and shorter than the agent’s auto-close). Sent once per pause; a new message re-arms it. Nothing is sent to the customer.
Conversation ended	conversation.ended	The conversation closed and the AI analysis finished — at most 15 minutes after the close. intel.status tells you whether the analysis is included.

Human handoff events

Event	type	When it is sent
Human requested	handoff.requested	The customer, an AI tool or a rule asked for a person.
Operator joined	operator.joined	An operator accepted the chat, took it over, forced it or received a transfer.
Operator left	operator.left	The operator closed the chat, handed it on, was replaced by an admin, or the session expired or the chat closed.
Handoff ended	handoff.ended	The human session is over: RESOLVED_BY_OPERATOR, NO_OPERATOR (nobody answered in time), EXPIRED or CHAT_CLOSED.

A transfer sends operator.left for the previous operator, then operator.joined for the new one.

Test conversations from the evaluation tools and Listen recordings never send hooks. Playground and real channel conversations do.

Create a hook

1. Open your agent and go to Lifecycle hooks.
2. Click New hook and fill in:
   • Endpoint URL — a public https:// address on port 443. Redirects are not followed.
   • Headers (optional) — for example the API key your endpoint expects. Values are stored encrypted and shown masked.
   • Events — one or more of the three above. Choosing Pause / Inactivity asks for the idle window in minutes.
   • Channels — leave empty for every channel, or pick some.
   • Data to send — the sections included in the payload (see below).
   • Body — the standard envelope, or your own JSON or form body built from variables. Or click Start from a template to load a ready-made hook (templates).
3. Click Save hook. The signing secret is shown once — copy it into your endpoint’s configuration. You can rotate it later; the old secret stops working at once.

An agent can have up to 5 hooks.

Choose the data

Send only what your system needs. Sections marked End only are available on conversation.ended only.

Section	Contents	Default
Contact	Name, e-mail, phone, channel id, tags, custom fields	On
First and last messages	The customer’s first and last message and the last reply	Off
AI analysis (end only)	Summary, outcome, sentiment, intent, topics, score	On
Lead (end only)	Lead score, interest, budget, timeframe	Off
Customer memory (end only)	The remembered preferences and profile	Off
Transcript (end only)	The customer-visible messages of the conversation	Off
Human handoff (end only)	Whether a person took part, the waits and the handling time	Off
Operator	Who handles the chat: the name the customer sees, title, department, public photo	Off
Operator e-mail	Your team member’s e-mail address	Off

Lead credits

Turning on Lead adds the lead analysis to every closed conversation of the agent. It is charged as CRM lead credits, even if no CRM is connected.

Personal data

Contact, messages, memory, transcript and the operator e-mail are personal data. You are responsible for how your endpoint stores and uses them. The delivery log never stores request bodies.

Custom body

The Standard body is the signed JSON envelope described in the reference. To send the shape your system expects instead, choose Custom JSON or Form and insert variables from the list next to the editor, for example:

{
  "ticket_id": "{{conversation.id}}",
  "customer": "{{contact.name}}",
  "summary": "{{intel.summary}}"
}

• Variables use {{path}} only — no helpers, loops or triple braces.
• A variable must be sent with every event the hook subscribes to, and its section must be turned on. The editor greys out the ones that are not.
• Values are escaped for you: a JSON string stays valid JSON, a form value is URL-encoded.
• A form body is a set of fixed field names, each with a value template.

The full list of variables is in the reference.

Test and monitor

• Send test event sends one signed request with made-up data and "test": true, so you can check your endpoint without a real conversation.
• Delivery log lists the last 30 days of deliveries with their attempts, status code and latency. Redeliver sends a finished event again with the same X-Synapsai-Webhook-Id.
• After 5 bad answers in a row (errors, timeouts, or a 2xx slower than 5 seconds) the hook is put in quarantine: its events are skipped, and it is checked automatically with a signed hook.ping until it answers again. Redeliver all skipped then sends the skipped events. The console shows it on the hook, on the home page and in the bell; nobody is e-mailed. See Quarantine.
• A 410 Gone answer pauses the hook at once. Turn it back on from the list when your endpoint is fixed.
• Changing a hook’s URL, or adding a personal data section, asks you to sign in again, and is recorded under the hook with who did it.

The complete guide has receivers for Node.js and AWS Lambda, ready to copy.