Skip to main content
When you create an agent, you can pass a returns object that describes the data you want out of the conversation. Every call that agent handles (inbound or outbound) runs against that schema. After the call ends, CallingBox reads the transcript and extracts those fields into structured JSON.

​
Defining a schema

Each key in returns is a field name. Each value is a type hint: "boolean", "string", or "number". 
agent = client.agents.create(
    name="Appointment confirmations",
    type="outbound",
    instructions="Confirm dental appointments. Offer to reschedule if needed.",
    returns={
        "confirmed": "boolean",
        "reschedule_to": "string",
        "reason": "string",
    },
    number_ids=["pn_abc123"],
)
The schema is snapshotted onto each call at dispatch time, so changing the agent later won’t retroactively change past calls.

​
Reading the result

Once the call finishes and extraction completes, the result field on the call object has the extracted data: 
{
  "result": {
    "confirmed": true,
    "reschedule_to": null,
    "reason": null
  },
  "result_status": "completed"
}
Fields that didn’t come up in the conversation come back as null.

​
Result statuses

Extraction is a separate step that runs after the call ends. Track it with result_status:
StatusWhat it means
pendingStill extracting
completedDone; data is in result
failedExtraction broke; reason is in result_error

​
When extraction doesn’t run

If the call ends without a real conversation (no answer, voicemail, busy), no extraction runs. All return fields come back as null and result_status stays pending. If the agent has no returns schema, the result field on every call from that agent is null.

​
Tips

  • Keep schemas flat. One level of keys with simple types works best.
  • Use descriptive field names. reschedule_to extracts better than field_2.
  • One goal per call. The more focused the instructions, the more accurate the extraction. If an agent has very different jobs, split it into multiple agents.

Agents

Where returns lives.

Outbound calls

Dispatch a call from an outbound agent.

Webhooks

Polling vs webhooks for getting results.

Call object

Every field on the call response.