Async Tools & Deferred Context

Build responsive Telnyx AI Assistants that keep talking while slow backends run. Use async webhooks and the Add Messages API together or independently.

Async tools allow your AI assistant to trigger long-running operations without blocking the conversation. Combined with the Add Messages API, you can inject results back into the conversation whenever they’re ready—whether that’s 5 seconds or 5 minutes later.

In this guide, you will learn:

• How to configure webhook tools to run asynchronously
• How to use the Add Messages API to inject context mid-conversation
• How to combine both features for powerful async workflows
• How to get the same behavior from tools served by an MCP server

---

Overview

Traditional webhook tools block the conversation until they complete. This works fine for fast operations, but creates awkward pauses for slow backend queries. Async tools solve this by letting the assistant continue the conversation while operations run in the background.

If your backend responds within a few seconds and you’d prefer to keep using sync webhooks, filler messages offer a simpler alternative — scripted phrases that play at timed intervals to fill silence while the webhook executes.

The two building blocks

These features are orthogonal—each is useful on its own, but they become especially powerful when combined.

Feature	What it does	Use alone
Async webhook flag	Lets the assistant continue talking while the webhook executes	Fire-and-forget operations (logging, notifications)
Add Messages API	Injects new context into an active conversation	External triggers, scheduled reminders, supervisor interventions

Combined workflow

When used together, these features enable a new pattern:

1. Assistant triggers an async webhook (e.g., order lookup)
2. Assistant continues chatting with the customer
3. Backend processes the request (5, 10, 30 seconds later)
4. Backend calls Add Messages API to inject the results
5. Assistant naturally incorporates the new information

This creates a seamless experience where the assistant stays engaged while slow operations complete in the background.

---

Async webhooks

The async flag on webhook tools tells the assistant not to wait for the response. The webhook fires, and the assistant immediately continues the conversation.

Configuring an async webhook

Set async: true in your webhook tool configuration:

{
  "type": "webhook",
  "webhook": {
    "name": "lookup_order_status",
    "description": "Triggers an async order status lookup. Results will be delivered automatically when ready.",
    "url": "https://your-backend.com/order-lookup",
    "method": "POST",
    "async": true,
    "headers": [
      {"name": "Content-Type", "value": "application/json"}
    ],
    "body_parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The customer's order ID"
        }
      },
      "required": ["order_id"]
    }
  }
}

Key configuration options

Field	Description
async	When true, the assistant continues without waiting for a response
url	Your backend endpoint that will process the request
method	HTTP method (typically POST)
body_parameters	JSON schema defining the parameters the assistant should provide

For the complete webhook tool schema, see the Create Assistant API reference.

What your backend receives

When the assistant triggers an async webhook, your endpoint receives:

• The configured body parameters (e.g., order_id)
• The x-telnyx-call-control-id header identifying the active call

POST /order-lookup HTTP/1.1
Content-Type: application/json
x-telnyx-call-control-id: v3:abc123def456...

{
  "order_id": "ORD-12345"
}

The x-telnyx-call-control-id header is critical—you’ll need it to inject results back into the conversation using the Add Messages API.

---

Add Messages API

The Add Messages API lets you inject new messages into an active conversation from outside the call flow. This is useful for delivering async results, supervisor interventions, or external triggers.

API endpoint

POST /v2/calls/{call_control_id}/actions/ai_assistant_add_messages

Request format

curl -X POST "https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_add_messages" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "Order ORD-12345 status: SHIPPED. Tracking: 1Z999AA10123456784. Estimated delivery: Tomorrow. Share this with the customer now."
      }
    ]
  }'

For the complete API specification, see the Add Messages API reference.

Message roles

Role	Use case	Prompts an assistant turn?
system	Instructions or context for the assistant (recommended for async results)	No. The content is absorbed as context and used on the assistant’s next turn.
user	Simulate user input	Yes. The assistant responds right away, and the text is recorded as something the caller said.
assistant	Inject assistant responses	No
tool	Deliver the result of an earlier tool call. Requires tool_call_id (see below).	No. Behaves like system: absorbed as context, used on the next turn.
developer	Developer-level instructions, as in the OpenAI message format	No

Pick the role by how the result should land in the conversation:

• The caller is still talking, or the result can wait for the next turn: use system (or tool). The assistant works the result into its next reply without interrupting anyone. If the caller goes quiet after asking, the platform’s own silence handling prompts the assistant, so the result is still delivered.
• The result must be spoken immediately, even unprompted: use user. This is the only role that starts a turn on its own. The trade-off is that the injected text appears in the transcript as caller speech and can interrupt a caller mid-sentence, so keep it short and label it, for example [SYSTEM: Order ORD-12345 is SHIPPED. Tell the caller now.].

Using role: tool and tool_call_id

A tool message must carry the tool_call_id of the call it answers. The id is required but not matched against the conversation’s outstanding calls: the API accepts a tool message whose id refers to a call that was already answered, and it does not reject an unknown id. Treat it as a label that helps the model relate the result to its earlier request, not as a correlation that the platform enforces.

Where to get the id:

• Mid-call: list the conversation’s messages with GET /v2/ai/conversations/{conversation_id}/messages. Assistant messages carry tool_calls[].id for every call the assistant made. MCP tools receive the conversation_id directly (_meta.telnyx_conversation_id); webhook tools receive the x-telnyx-call-control-id header instead and can look the conversation up with GET /v2/ai/conversations?metadata->call_control_id=eq.{call_control_id}.
• After the call: with telephony_settings.conversation_ended_full_history: true, the call.conversation.ended webhook includes the full message history with the same ids.

Because the id is not enforced, tool buys you nothing over system for timing. Use it when you want the transcript to show a proper tool result, and system otherwise.

Standalone use cases

The Add Messages API is valuable even without async webhooks:

• Supervisor intervention: A human supervisor injects guidance during a difficult call
• Scheduled reminders: External system reminds the assistant about time-sensitive information
• Cross-system triggers: CRM or ticketing system pushes updates to an active call
• Escalation prompts: Monitoring system detects frustration and injects de-escalation guidance

---

Combining async webhooks with Add Messages

The real power comes from combining these features. Here’s a complete example of an async order lookup system.

Architecture

┌─────────────┐     1. Trigger async webhook      ┌─────────────────┐
│             │ ──────────────────────────────────▶│                 │
│  Assistant  │                                    │  Your Backend   │
│             │◀────────────────────────────────── │                 │
└─────────────┘     4. Add Messages API            └─────────────────┘
       │                    ▲                              │
       │                    │                              │
       ▼                    │                              ▼
  2. Continue          3. Process request           Query databases,
  conversation         (5-30 seconds)               external APIs, etc.

Step 1: Configure the assistant

Create an assistant with async webhook tools. Notice how the instructions tell the assistant to continue engaging while waiting:

{
  "name": "Customer Service Agent",
  "instructions": "You are a helpful customer service agent for Acme Electronics.\n\nWhen a customer asks about an order, trigger the lookup_order_status tool. This runs asynchronously—results will arrive automatically in 10-20 seconds.\n\nAfter triggering the lookup, keep the customer engaged:\n- Mention current promotions\n- Ask about their experience\n- Offer to help with anything else\n\nWhen results arrive, naturally incorporate them: \"Great news, I have your order info now!\"",
  "tools": [
    {
      "type": "webhook",
      "webhook": {
        "name": "lookup_order_status",
        "description": "Async order lookup. Results delivered automatically when ready.",
        "url": "https://your-backend.com/order-lookup",
        "method": "POST",
        "async": true,
        "body_parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string", "description": "Order ID to look up"}
          },
          "required": ["order_id"]
        }
      }
    }
  ]
}

Step 2: Build the backend service

Your backend receives the webhook, processes the request, and calls the Add Messages API when done:

import os
import time
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
TELNYX_API_KEY = os.environ.get("TELNYX_API_KEY")

@app.route("/order-lookup", methods=["POST"])
def order_lookup():
    data = request.get_json(silent=True) or {}

    # Get the call control ID from headers
    call_control_id = request.headers.get("x-telnyx-call-control-id")
    order_id = data.get("order_id")

    if not call_control_id:
        return jsonify({"error": "Missing call control ID"}), 400

    # Simulate slow backend query (replace with real logic)
    time.sleep(15)

    # Build the result message
    result = {
        "status": "SHIPPED",
        "tracking": "1Z999AA10123456784",
        "delivery": "Tomorrow"
    }

    system_message = f"""[ORDER LOOKUP COMPLETE]
Order {order_id}: {result['status']}
Tracking: {result['tracking']}
Estimated delivery: {result['delivery']}
Share these details with the customer now."""

    # Inject results back into the conversation
    inject_message(call_control_id, system_message)

    return jsonify({"status": "sent"})


def inject_message(call_control_id: str, message: str):
    """Send a message to an active conversation via Add Messages API."""
    url = f"https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_add_messages"

    response = requests.post(
        url,
        headers={
            "Authorization": f"Bearer {TELNYX_API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "messages": [{"role": "system", "content": message}]
        }
    )

    return response.json()


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

Step 3: Test the flow

1. Call your assistant and ask about an order
2. The assistant triggers the async lookup and continues chatting
3. After 15 seconds, your backend injects the results
4. The assistant seamlessly shares the order details

---

Async tools served by an MCP server

The async flag belongs to webhook tools only. An MCP server attached with mcp_servers exposes id and allowed_tools and nothing else: there is no per-tool async, timeout, or filler setting, and the assistant waits for the MCP tools/call to return before it can take new caller input. Filler messages do apply to MCP tool calls, but they narrate the wait rather than end it.

To get deferred behavior from an MCP tool, build it into the tool itself:

1. Return fast. As soon as the tool knows the work will be slow, return a short “started” result (for example Lookup started for order ORD-12345; result will follow.) and keep the real work running in the background. The assistant can carry on talking while it runs.

2. Correlate. Each tools/call request from Telnyx carries the live conversation id in the JSON-RPC params._meta object (not in an HTTP header):

   { "_meta": { "telnyx_conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }
   

   Keep it with the background job. To call Add Messages you also need the call_control_id: fetch it from the conversation’s metadata with GET /v2/ai/conversations/{conversation_id} (metadata.call_control_id), or record the mapping when the call starts from the dynamic variables webhook, whose assistant.initialization payload carries call_control_id.

3. Inject the result with the Add Messages API exactly as you would for an async webhook, choosing the role as described in Message roles. Include the identifier from step 1 so the assistant can tie the result back to the request.

Do not combine filler messages with a “started” result for the same tool: the filler plays while the tool runs, and a tool that returns immediately leaves nothing to fill, so the two compete.

---

Multiple parallel lookups

You can trigger multiple async webhooks simultaneously. Each completes independently and injects results as they become available.

Example: Staggered results

Configure multiple tools with different backend processing times:

Tool	Processing time	Information returned
check_loyalty_points	~10 seconds	Points balance, membership tier
lookup_order_status	~20 seconds	Order status, tracking, delivery estimate

The assistant triggers both at once. Results drip into the conversation naturally:

Customer: "Where's my order 12345?"

Agent: [Triggers both lookups] "Let me pull that up for you! By the way,
       we're running 20% off all accessories this week."

[10 seconds pass - loyalty results arrive]

Agent: "Oh nice, I see you have 2,500 reward points - that's Gold status!
       You've got $25 to use on your next purchase."

[20 seconds pass - order results arrive]

Agent: "And here's your order info - order 12345 is out for delivery!
       Tracking number is 1Z999AA10123456784, should arrive tomorrow."

Instructing the assistant

For parallel lookups to work well, your assistant instructions should emphasize calling tools together:

When a customer asks about an order, trigger BOTH lookup tools at the same time:
1. check_loyalty_points
2. lookup_order_status

Do not wait for one to complete before calling another. Call both immediately.
Results will arrive automatically as each lookup completes.

---

Best practices

Crafting system messages

When injecting results via the Add Messages API, format them clearly:

# Good - Clear, actionable
system_message = """[ORDER LOOKUP COMPLETE]
Order ORD-12345: SHIPPED
Tracking: 1Z999AA10123456784
Estimated delivery: Tomorrow
Share these details with the customer now."""

# Avoid - Ambiguous
system_message = "The order was found in the system."

Handling edge cases

Call ended before results arrive:

response = inject_message(call_control_id, message)
if response.get("status_code") == 404:
    # Call has ended, log and move on
    print(f"Call {call_control_id} already ended")

Multiple results for same lookup:

• Include identifiers in messages so the assistant knows which query the results belong to
• Use timestamps or request IDs if needed

Backend considerations

• Your backend should return a 200 response quickly to acknowledge receipt
• Process the actual work asynchronously (use background workers, Celery, AWS Lambda, etc.)
• There’s no timeout constraint on async webhooks—your backend can take as long as needed before calling the Add Messages API

Testing tips

• Use tools like ngrok to expose local backends during development
• Webhook tools: log all headers to verify x-telnyx-call-control-id is received. MCP tools: it is not a header; log the parsed tools/call request and check params._meta.telnyx_conversation_id
• Test with various delay lengths to ensure natural conversation flow
• Monitor the conversation transcript in the Portal to see messages being injected

---

Use cases

Customer service

• Order lookups: Query multiple systems (warehouse, shipping, payments) in parallel
• Account reviews: Pull account history, loyalty status, and recent tickets simultaneously
• Product availability: Check inventory across multiple warehouses

Healthcare

• Patient record retrieval: Fetch records from multiple systems while confirming appointment details
• Insurance verification: Run eligibility checks while gathering patient information
• Lab results: Query lab systems and deliver results when ready

Financial services

• Loan pre-qualification: Run credit checks and affordability calculations in background
• Account aggregation: Pull balances from multiple accounts simultaneously
• Fraud alerts: Inject real-time fraud warnings from monitoring systems

Scheduling

• Multi-calendar availability: Check availability across multiple calendars/resources
• Booking confirmations: Process reservations and inject confirmation details
• Waitlist updates: Notify assistant when spots become available

---

Related resources

• Add Messages API Reference - Complete API specification for injecting messages
• Create Assistant API Reference - Full webhook tool configuration options
• Filler Messages - Scripted phrases that fill silence during sync webhook calls
• Webhooks & Workflows - Learn more about configuring webhook tools
• Dynamic Variables - Pass context into conversations at start time
• Memory - Persist information across conversations