Async Tools & Deferred Context

{
  "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"]
    }
  }
}

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

{
  "order_id": "ORD-12345"
}

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

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."
      }
    ]
  }'

┌─────────────┐     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.

{
  "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"]
        }
      }
    }
  ]
}

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)

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."

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.

# 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."

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")