Calls & Playbook

Configure the AI coach that listens on live sales calls, and pull back the call history it produced — over both REST and MCP.

Two surfaces share the same data. The Sales Playbook drives what the live-call coach knows: a base coaching prompt, a set of call types (each with its own script, checklist, and prompt additions), and reference documents. The Call History surface is read-only recall of completed calls — transcript, checklist coverage, sentiment, lead verdict, and drafted emails.

Authentication

REST endpoints accept an API key as a bearer token: Authorization: Bearer avs_YOUR_API_KEY. The same key authorizes the MCP server, where tenant scope comes from the connected agent's context. See Authentication for how to obtain a key.

REST — Playbook Configuration

Base path /api/v1/playbook. All numeric IDs are integers.

GET /api/v1/playbook

Returns the whole playbook. The appliesTo value is one of Phone, Video, or Both.

{
    "success": true,
    "data": {
        "id": 1,
        "baseCoachingPrompt": "You are a discovery-call coach. Keep the rep curious...",
        "callTypes": [
            {
                "id": 4,
                "name": "Discovery Call",
                "appliesTo": "Phone",
                "isDefault": true,
                "isActive": true,
                "promptAdditions": "Probe for budget authority before pitching.",
                "endGoal": "Book a 30-minute discovery demo",
                "callScript": "Open with the referral source, then ask...",
                "checklist": [
                    { "text": "Confirmed decision maker", "coverageHint": "Ask who signs off" },
                    { "text": "Identified pain point", "coverageHint": null }
                ]
            }
        ],
        "documents": [
            { "id": 2, "title": "Objection Handling", "content": "When they say it's too expensive..." }
        ],
        "updatedAt": "2026-06-18T14:22:05Z"
    },
    "timestamp": "2026-06-18T14:30:00Z"
}

PUT /api/v1/playbook/coaching-prompt

Replaces the base prompt. Call types and documents are preserved.

Request body

{
    "baseCoachingPrompt": "You are a discovery-call coach. Keep the rep curious..."
}

POST /api/v1/playbook/call-types

Creates a call type. appliesTo defaults to Phone; isActive defaults to true. endGoal is optional — the outcome this call drives toward, which the live AI coach steers every suggestion toward. Each checklist item has a text and an optional coverageHint.

Request body

{
    "name": "Discovery Call",
    "appliesTo": "Phone",
    "isDefault": true,
    "isActive": true,
    "promptAdditions": "Probe for budget authority before pitching.",
    "endGoal": "Book a 30-minute discovery demo",
    "callScript": "Open with the referral source, then ask...",
    "checklist": [
        { "text": "Confirmed decision maker", "coverageHint": "Ask who signs off" }
    ]
}

The response wraps the created call type (with its new id) in the standard envelope.

DELETE /api/v1/playbook/call-types/{id}

{
    "success": true,
    "data": { "id": 4, "deleted": true },
    "timestamp": "2026-06-18T14:30:00Z"
}

REST — Call History (read-only)

Base path /api/v1/calls. Recall only — billing and internal fields are never returned (see the callout below).

Query parameters for /api/v1/calls

The filtered list adds totalHours and totalCredits aggregates; the recent list omits them.

{
    "success": true,
    "data": {
        "count": 2,
        "totalHours": 0.85,
        "totalCredits": 51,
        "calls": [
            {
                "id": 318,
                "source": "Browser",
                "callTypeId": 4,
                "status": "Completed",
                "startedAt": "2026-06-18T13:02:11Z",
                "endedAt": "2026-06-18T13:23:48Z",
                "durationSeconds": 1297,
                "fromNumber": "+15125551212",
                "toNumber": "+16317454144",
                "contactName": "Dana Reyes",
                "companyName": "Northside Integrators",
                "outcome": "Interested",
                "coverageCovered": 5,
                "coverageTotal": 6
            }
        ]
    },
    "timestamp": "2026-06-18T14:30:00Z"
}

GET /api/v1/calls/{id} returns the same fields plus summary, nextSteps, and the parsed JSON columns transcript, checklistResults, sentiment, leadVerdict, and emails.

MCP Tools

The same configuration and recall are available to AI agents as MCP tools. Tool inputs and outputs use snake_case. Connect the MCP server as described in MCP Server.

Playbook configuration tools

Call recall tools

The optional end_goal parameter sets the outcome the call drives toward; the live AI coach steers every suggestion toward it. The checklist_json parameter takes a raw JSON array. Note the casing asymmetry: input items use coverageHint, while tool output renders it as coverage_hint.

{
    "id": 4,
    "name": "Discovery Call",
    "applies_to": "Phone",
    "is_default": true,
    "is_active": true,
    "prompt_additions": "Probe for budget authority before pitching.",
    "end_goal": "Book a 30-minute discovery demo",
    "call_script": "Open with the referral source, then ask...",
    "checklist": [
        { "text": "Confirmed decision maker", "coverage_hint": "Ask who signs off" }
    ]
}

Recall tools return snake_case fields. A list_calls item:

{
    "count": 1,
    "calls": [
        {
            "id": 318,
            "source": "Browser",
            "call_type_id": 4,
            "status": "Completed",
            "started_at": "2026-06-18T13:02:11Z",
            "ended_at": "2026-06-18T13:23:48Z",
            "duration_seconds": 1297,
            "from_number": "+15125551212",
            "to_number": "+16317454144",
            "contact_name": "Dana Reyes",
            "company_name": "Northside Integrators",
            "outcome": "Interested",
            "coverage_covered": 5,
            "coverage_total": 6
        }
    ]
}

MCP errors are flat: { "error": "not_found" } for a missing ID, and { "error": "invalid", "message": "..." } for a bad value. Deletes return { "success": true, "id": 4, "deleted": true }.

Error codes (REST)