Call Lifecycle Hooks

Integrate your own systems with SquawkVoice’s call lifecycle so your AI Agent can greet callers with full context and push rich call outcomes back when the conversation ends. This guide explains how to wire up Pre-conversation and Post-conversation Actions specifically for SIP-based telephony integrations.

Open your agent from Build → AI Agents and you’ll find Pre-conversation Actions, In-conversation Actions and Post-conversation Actions as cards under Actions & Integrations. This page covers the first and the last.

Lifecycle Overview

Every inbound call follows a three-phase lifecycle. Pre-conversation and Post-conversation Actions let you hook into the first and last phases to exchange data with your backend.

Pre-conversation Actions — Fetching Caller Context

A Pre-conversation Action is configured as a visual flow that fires after the SIP INVITE is received but before the agent speaks. Use the flow’s API Request node to look up the caller in your CRM, ticketing system, or any backend so the agent can personalise its greeting from the very first sentence.

What You Can Send

Your Pre-conversation Action request can include these built-in call variables as query parameters or in the request body, along with any variable you set earlier in the flow:

Variable	Description	Example
`{{interaction.ANI}}`	Caller’s phone number (ANI)	`+14155551234`
`{{interaction.DNIS}}`	Called number (DNIS)	`+18005559876`
`{{interaction.CALL_SID}}`	Unique call session identifier	Generated for each call
`{{interaction.CURRENT_DATE}}`	Today’s date in the AI Agent’s configured timezone	`2026-03-14`
`{{interaction.CHANNEL}}`	The channel the conversation is running on	`voice`

{{interaction.ANI}} and {{interaction.DNIS}} arrive exactly as your carrier or SBC presents them. For ordinary phone numbers that is usually E.164, as in the examples above, but on a SIP trunk either one may arrive as a SIP address, such as sip:4155551234@sbc.example.com. If your CRM expects E.164, strip the sip: prefix and the host before you look the caller up, and place a test call through your trunk to see the real value.When your PBX forwards the call to your SquawkVoice number, {{interaction.DNIS}} is the number the caller originally dialled. Otherwise it is the address the call was sent to.

SIP header values aren’t available as variables. The one header SquawkVoice reads on an inbound call is X-SIP-AssistantId, which only chooses the AI Agent — see Mapping the Call to an AI Agent. If your backend needs an ID of its own, such as a customer or account number, look it up from {{interaction.ANI}} in your Pre-conversation Action.

What You Get Back

Inside the API Request node of your Pre-conversation flow, save fields from your API response into variables that stay available throughout the entire call. Select Send to run the request, then use the JSON Path Expressions table under the response. In each row, enter the field’s JSON Path (for example $.firstName), pick or create the Variable that should hold it, and optionally set a Default Value for when the field is missing or empty in the response. Clicking a field in the response’s Data view fills in its path for you.

Response Field	Variable	Usage Example
`firstName`	`{{firstName}}`	Greeting message: “Hi `{{firstName}}`, thanks for calling.”
`accountStatus`	`{{accountStatus}}`	Guidelines: “If `{{accountStatus}}` is overdue, offer a payment plan.”
`lastInteraction`	`{{lastInteraction}}`	Context for the AI: “Customer last contacted us about `{{lastInteraction}}`”

The agent’s Greeting message (Greeting & Sign-off → Voice) and Guidelines are filled in once, after the Pre-conversation Actions have run, so plan your lookup to return everything the agent needs up front. They can use variables set by Pre-conversation Actions, the built-in call variables ({{interaction.ANI}}, {{interaction.DNIS}}, {{interaction.CALL_SID}}, {{interaction.CURRENT_DATE}} and {{interaction.CHANNEL}}), agent values such as {{agent.TIMEZONE}}, and any variable that has a Default value. Values that only exist during or after the call, such as the transcript and summary or anything an In-conversation or Post-conversation Action sets, aren’t available yet.

Example: CRM Lookup by Caller ID

GET https://api.example.com/crm/caller?phone={{interaction.ANI}}

Response:

{
  "firstName": "Sarah",
  "accountStatus": "active",
  "accountId": "ACC-92841",
  "lastInteraction": "billing query on 28 Feb"
}

In the API Request node’s JSON Path Expressions table, add one row for each field (for example $.firstName → firstName), then reference the variables in your agent’s Greeting message:

“Hi {{firstName}}, welcome back! I can see your account {{accountId}} is {{accountStatus}}. How can I help you today?”

Post-conversation Actions — Returning Call Context

A Post-conversation Action is configured as a visual flow that fires after the conversation ends — whether the caller hung up, the agent ended the call, or a handoff occurred. Use it to push the call outcome back to your systems.

Available Interaction Variables

SquawkVoice automatically generates rich context at the end of every call. Use these built-in variables in your Post-conversation Action request body:

Variable	Description
`{{interaction.SUMMARY}}`	AI-generated natural-language summary of the conversation
`{{interaction.BRIEF_SUMMARY}}`	Condensed summary (255 characters or less) — useful for CRM fields with length limits
`{{interaction.TRANSCRIPT}}`	Full conversation transcript
`{{interaction.DISPOSITION}}`	The outcome recorded for the call, such as `Hangup`, `Caller-Hungup` or one of your own outcome options (see below)
`{{interaction.CALL_DURATION}}`	Call duration in seconds
`{{interaction.CALL_SID}}`	Unique call session identifier
`{{interaction.ANI}}`	Caller’s phone number (ANI)
`{{interaction.DNIS}}`	Called number (DNIS)
`{{interaction.CURRENT_DATE}}`	The current date based on the AI Agent’s configured timezone
`{{interaction.CHANNEL}}`	The channel the conversation ran on: `voice`, `chat` or `email`
`{{interaction.TRANSFER_DESTINATION}}`	The phone number or SIP address the call was transferred to, when the agent transferred it
Any custom variable	Variables set during Pre-conversation or In-conversation Actions (e.g. `{{accountId}}`, `{{ticketNumber}}`)

{{interaction.DISPOSITION}} is the exact name of an outcome, so match it with the same capital letters, hyphens and spaces. On a voice call it is one of these:

Hangup when the conversation reached its natural end: the agent ended the call, or the caller hung up after being helped. Call History shows these calls as Contained, but your backend receives Hangup.
Caller-Hungup when the caller hung up before that.
One of your own Outcome options when the agent transfers the call. The agent picks the one that best describes the reason, and you add them under Handoff → Voice → Outcome options.
Voicemail, Wrong Number, DNC Request or Callback Requested on calls from agents assigned to an outbound campaign.
INSUFFICIENT_BALANCE when the call ended because the balance couldn’t cover the next minute.

Values such as resolved or escalated only appear if you’ve created outcome options with those names.

Example: Pushing Call Outcome to Your Backend

POST https://api.example.com/calls/complete
Content-Type: application/json

Request body:

{
  "callerPhone": "{{interaction.ANI}}",
  "calledNumber": "{{interaction.DNIS}}",
  "callSid": "{{interaction.CALL_SID}}",
  "accountId": "{{accountId}}",
  "summary": "{{interaction.SUMMARY}}",
  "transcript": "{{interaction.TRANSCRIPT}}",
  "disposition": "{{interaction.DISPOSITION}}",
  "duration": "{{interaction.CALL_DURATION}}",
  "ticketNumber": "{{ticketNumber}}"
}

Your backend can then:

Update the CRM with the call summary and disposition
Create or close a support ticket based on the outcome
Trigger workflows (e.g. send a follow-up email, schedule a callback)
Store the transcript for compliance and quality assurance

Design your backend endpoint to accept a single payload containing all the fields you need. This keeps the integration simple and avoids multiple network calls.

Example: End-to-End Flow

Here’s a complete scenario showing how a business that connects its phone system to SquawkVoice over SIP uses both lifecycle hooks:

Caller Dials In

A customer calls your inbound number. Your PBX routes the call to SquawkVoice via SIP, and the number — added in Studio as a BYO Number and assigned to an agent — resolves to the right AI Agent. See Mapping the Call to an AI Agent.

Pre-conversation: CRM Lookup

SquawkVoice fires the Pre-conversation Action, calling your CRM API with the caller’s phone number. The response populates firstName, accountId, and accountStatus.

AI Conversation

The agent greets the caller by name, references their account, and resolves a billing enquiry. An In-conversation Action creates a support ticket and stores the ticketNumber variable.

Post-conversation: Push Outcome

After the call ends, the Post-conversation Action sends the AI summary, full transcript, disposition, and ticket number back to your backend. The CRM record is updated automatically.

Best Practices

Keep pre-conversation latency low — The Pre-conversation Action runs before the agent speaks. Use a fast endpoint and return only the fields you need.
Use meaningful variable names — Names like {{accountStatus}} are easier to reference in prompts than {{field1}}.
Make post-conversation endpoints idempotent — The same call payload may be retried; design your backend to handle duplicates gracefully.
Secure your endpoints — Use Auth Profiles with API keys or mTLS to protect data in transit.
Test with the built-in request tester — Use the Send button in the API Request node of the flow editor to verify your request and your JSON Path Expressions before going live.
Cross-reference the Action docs — For detailed setup steps, see Pre-conversation Actions and Post-conversation Actions in the Build guide.

Get Started

Build

Campaigns

Optimize

Manage

Best Practices

Library

Telephony

Product

Trust & Security

Lifecycle Overview

Pre-conversation Actions — Fetching Caller Context

What You Can Send

What You Get Back

Example: CRM Lookup by Caller ID

Post-conversation Actions — Returning Call Context

Available Interaction Variables

Example: Pushing Call Outcome to Your Backend

Example: End-to-End Flow

Best Practices

​Lifecycle Overview

​Pre-conversation Actions — Fetching Caller Context

​What You Can Send

​What You Get Back

​Example: CRM Lookup by Caller ID

​Post-conversation Actions — Returning Call Context

​Available Interaction Variables

​Example: Pushing Call Outcome to Your Backend

​Example: End-to-End Flow

​Best Practices

Lifecycle Overview

Pre-conversation Actions — Fetching Caller Context

What You Can Send

What You Get Back

Example: CRM Lookup by Caller ID

Post-conversation Actions — Returning Call Context

Available Interaction Variables

Example: Pushing Call Outcome to Your Backend

Example: End-to-End Flow

Best Practices