> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squawkvoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Call Lifecycle Hooks
> Use pre-call and post-call actions to exchange caller context with your telephony platform
Integrate your partner 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-Call and Post-Call Actions specifically for SIP-based telephony integrations.
## Lifecycle Overview
Every inbound call follows a three-phase lifecycle. Pre-call and post-call actions let you hook into the first and last phases to exchange data with your backend.
```mermaid theme={null}
sequenceDiagram
participant Caller
participant Partner as Partner PBX / SBC
participant SV as SquawkVoice
participant Backend as Partner Backend
Caller->>Partner: Inbound call
Partner->>SV: SIP INVITE + X-SIP-AssistantId
rect rgb(59,130,246)
Note over SV,Backend: Pre-Call Phase
SV->>Backend: GET /caller?ani=ANI
Backend-->>SV: firstName, accountStatus, ...
end
rect rgb(16,185,129)
Note over SV,Caller: AI Conversation
SV->>Caller: Personalised greeting + conversation
Caller->>SV: Conversation proceeds
end
rect rgb(245,158,11)
Note over SV,Backend: Post-Call Phase
SV->>Backend: POST /call-complete
Note right of SV: summary, transcript,
disposition, variables
Backend-->>SV: 200 OK
end
```
***
## Pre-Call Actions — Fetching Caller Context
A **Pre-Call 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-Call Action request can include any available call metadata as query parameters or in the request body:
| Variable | Description | Example |
| --------------------------- | ------------------------------------------ | -------------------- |
| `{{interaction.ANI}}` | Caller's phone number (ANI) | `+14155551234` |
| `{{interaction.DNIS}}` | Called number (DNIS) | `+18005559876` |
| Any custom SIP header value | Values extracted from incoming SIP headers | Partner-specific IDs |
### What You Get Back
Inside the API Request node of your Pre-Call flow, map fields from your API response to variables that become available throughout the entire call:
| Response Field | Variable | Usage Example |
| ----------------- | --------------------- | ------------------------------------------------------------------------------ |
| `firstName` | `{{firstName}}` | Initial 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}}`"* |
Variables created in Pre-Call Actions are the **only** variables available in the agent's **Initial Message** and **Guidelines**. Plan your lookup to return everything the agent needs up front.
### Example: CRM Lookup by Caller ID
```
GET https://api.partner.com/crm/caller?phone={{interaction.ANI}}
```
Response:
```json theme={null}
{
"firstName": "Sarah",
"accountStatus": "active",
"accountId": "ACC-92841",
"lastInteraction": "billing query on 28 Feb"
}
```
Configure the API Request node to map each field to a variable, then reference them in your agent's Initial Message:
> *"Hi `{{firstName}}`, welcome back! I can see your account `{{accountId}}` is `{{accountStatus}}`. How can I help you today?"*
***
## Post-Call Actions — Returning Call Context
A **Post-Call 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-Call 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}}` | Call disposition determined by the AI (e.g. `resolved`, `escalated`, `callback_requested`) |
| `{{interaction.CALL_DURATION}}` | Call duration |
| `{{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 |
| Any custom variable | Variables set during Pre-Call or During-Call Actions (e.g. `{{accountId}}`, `{{ticketNumber}}`) |
### Example: Pushing Call Outcome to Partner Backend
```
POST https://api.partner.com/calls/complete
Content-Type: application/json
```
Request body:
```json theme={null}
{
"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 Partner Flow
Here's a complete scenario showing how a SIP partner uses both lifecycle hooks:
A customer calls the partner's inbound number. The partner PBX routes the call to SquawkVoice via SIP, injecting the `X-SIP-AssistantId` header.
SquawkVoice fires the Pre-Call Action, calling the partner's CRM API with the caller's phone number. The response populates `firstName`, `accountId`, and `accountStatus`.
The agent greets the caller by name, references their account, and resolves a billing enquiry. A During-Call Action creates a support ticket and stores the `ticketNumber` variable.
After the call ends, the Post-Call Action sends the AI summary, full transcript, disposition, and ticket number back to the partner's backend. The CRM record is updated automatically.
***
## Best Practices
* **Keep pre-call latency low** — The Pre-Call 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-call 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 response mapping before going live.
* **Cross-reference the Action docs** — For detailed setup steps, see [Pre-Call Actions](/build/ai-agents/pre-call-actions) and [Post-Call Actions](/build/ai-agents/post-call-actions) in the Build guide.