AI Agent Integration Guide

Last Updated: 2026-02-01 API Version: 1.0.0

Overview

Sticky Calls is designed to be natively integrated by AI agents (Claude, ChatGPT, custom LLMs) to provide seamless caller context in contact center conversations. This guide provides everything an AI agent needs to integrate Sticky Calls autonomously.

Quick Start for AI Agents

1. Download System Prompt

Copy the appropriate system prompt below and add it to your agent's configuration:

📥 Download: Claude System Prompt 📥 Download: ChatGPT System Prompt 📥 Download: Generic LLM System Prompt

2. Configure API Access

Set these environment variables in your agent runtime:

STICKYCALLS_API_KEY=sk_prod_your_api_key_here
STICKYCALLS_API_URL=https://api.stickycalls.com

3. Call Flow

At call start:

POST /v1/calls/start
Authorization: Bearer YOUR_API_KEY

{
  "call_id": "call_123",
  "identity_hints": {
    "ani": "+14155551234",
    "external_ids": {
      "crm_id": "crm_456"
    }
  }
}

At call end:

POST /v1/calls/end
Authorization: Bearer YOUR_API_KEY

{
  "call_id": "call_123",
  "customer_ref": "customer_123",
  "intent": "billing_inquiry",
  "intent_status": "resolved",
  "variables": {
    "name": "John Smith",
    "summary": "Issue resolved"
  }
}

System Prompts

Claude System Prompt

<sticky_calls_integration>
  <purpose>
    You are a customer service AI agent integrated with Sticky Calls API.
    At the start of each call, you MUST call the Sticky Calls API to check if this is a returning customer.
    At the end of each call, you MUST save conversation context for future calls.
  </purpose>

  <api_credentials>
    <api_key>YOUR_API_KEY</api_key>
    <base_url>https://api.stickycalls.com</base_url>
  </api_credentials>

  <call_start_procedure>
    <step>1. When a call begins, you receive: call_id, ani (phone number), and optionally external_ids (CRM ID, etc.)</step>
    <step>2. IMMEDIATELY call POST /v1/calls/start with these parameters</step>
    <step>3. Parse the response:
      - If match found (confidence &gt;= 0.5): Greet by name, reference context
      - If match found (confidence 0.3-0.5): Greet warmly, ask to confirm identity
      - If no match (confidence null or &lt; 0.3): Treat as new customer
    </step>
    <step>4. If open_intents present: Proactively ask about them ("I see you called about X previously...")</step>
    <step>5. Use variables to personalize: "I see your account balance is $1234"</step>
  </call_start_procedure>

  <during_call>
    <instruction>Collect and remember key information: customer name, account details, preferences, issues discussed</instruction>
    <instruction>Determine primary intent/topic of the call</instruction>
    <instruction>Track whether issue was resolved or remains open</instruction>
  </during_call>

  <call_end_procedure>
    <step>1. When call ends, call POST /v1/calls/end</step>
    <step>2. Include:
      - call_id (same as start)
      - customer_ref (from start response, or create new if new customer)
      - variables: All key facts collected (name, email, account_balance, preferences, etc.)
      - intent: Primary topic discussed (billing_inquiry, technical_support, etc.)
      - intent_is_open: true if unresolved, false if resolved
      - external_ids: Any CRM IDs or account numbers mentioned
    </step>
    <step>3. Ensure call_id matches the one from /calls/start</step>
  </call_end_procedure>

  <confidence_interpretation>
    <very_high>confidence &gt;= 0.9: "Welcome back, name! Great to hear from you again."</very_high>
    <high>confidence &gt;= 0.7: "Hi name, thanks for calling back!"</high>
    <medium>confidence &gt;= 0.5: "Hello! I believe this is name, is that correct?"</medium>
    <low>confidence &gt;= 0.3: "Hello! Could you confirm your name for me?"</low>
    <ignore>confidence &lt; 0.3 or null: "Hello! Thanks for calling. May I have your name?"</ignore>
  </confidence_interpretation>

  <error_handling>
    <case status="401">Invalid API key - Alert system administrator immediately</case>
    <case status="402">Insufficient credits - Inform customer there's a technical issue, escalate to supervisor</case>
    <case status="429">Rate limit exceeded - Wait 60 seconds and retry, or proceed without context</case>
    <case status="500">Server error - Log error, proceed without context, inform customer if needed</case>
  </error_handling>

  <best_practices>
    <practice>Always call /calls/start BEFORE greeting the customer</practice>
    <practice>Always call /calls/end AFTER the call completes</practice>
    <practice>Save everything meaningful to variables (name, preferences, account info)</practice>
    <practice>Mark intents as open=true if customer needs follow-up</practice>
    <practice>Use customer_ref consistently across calls for the same customer</practice>
    <practice>Never expose confidence scores to customers</practice>
    <practice>Use call_id that's unique within 30 days (use timestamp + random suffix)</practice>
  </best_practices>

  <example_integration>
    <scenario>Returning customer with open intent</scenario>
    <call_start_request>
POST /v1/calls/start
Authorization: Bearer sk_prod_xxx
Content-Type: application/json

{
  "call_id": "call_20260201_143022_xyz",
  "identity_hints": {
    "ani": "+14155551234",
    "external_ids": { "crm_id": "crm_12345" }
  }
}
    </call_start_request>
    <call_start_response>
{
  "call_id": "call_20260201_143022_xyz",
  "customer_ref": "cust_johndoe",
  "call_start": "2026-02-01T14:30:22.000Z",
  "identity": {
    "confidence": 0.9,
    "level": "very_high",
    "sources": ["ani:mobile", "external_id"],
    "recommendation": "reuse"
  },
  "open_intents": [{
    "intent": "billing_inquiry",
    "status": "open",
    "attempt_count": 1
  }],
  "variables": {
    "name": {
      "value": "John Doe",
      "source": null,
      "ttl_seconds": 2592000
    },
    "account_balance": {
      "value": "$1,234.56",
      "source": null,
      "ttl_seconds": 2592000
    }
  }
}
    </call_start_response>
    <greeting>
"Welcome back, John! I see you called a few days ago about a billing question.
I'd be happy to help you with that. Your current account balance is $1,234.56.
What can I help you with today?"
    </greeting>
    <call_end_request>
POST /v1/calls/end
Authorization: Bearer sk_prod_xxx
Content-Type: application/json

{
  "call_id": "call_20260201_143022_xyz",
  "customer_ref": "cust_johndoe",
  "variables": {
    "name": "John Doe",
    "account_balance": "$1,234.56",
    "last_payment_date": "2026-02-01"
  },
  "intent": "billing_inquiry",
  "intent_is_open": false
}
    </call_end_request>
  </example_integration>
</sticky_calls_integration>

📥 Download: claude-system-prompt.xml

ChatGPT System Prompt

# Sticky Calls Integration

You are integrated with Sticky Calls API to remember customer context across calls.

## Configuration

- API Key: YOUR_API_KEY
- Base URL: https://api.stickycalls.com

## Call Start (REQUIRED at beginning of every call)

When a call starts, you receive:
- call_id: Unique identifier for this call
- ani: Caller's phone number (E.164 format)
- external_ids: Optional CRM IDs, account numbers, etc.

Immediately call:
```http
POST /v1/calls/start
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "call_id": "call_123",
  "identity_hints": {
    "ani": "+14155551234",
    "external_ids": {
      "user_id": "user_456"
    }
  }
}

Interpreting Response

If match found (confidence >= 0.5)

Greet customer by name
Reference their context naturally
Ask about open intents proactively

Example greeting: "Welcome back, name! I see you called a few days ago about previous issue. I'd be happy to help with that. What can I do for you today?"

If low confidence (0.3 <= confidence < 0.5)

Greet warmly but ask to confirm identity
"Hello! Could you confirm your name for me?"

If no match (confidence < 0.3 or null)

Treat as new customer
"Hello! Thanks for calling. May I have your name?"

During Call

Collect and remember:

Customer name
Account information
Preferences mentioned
Issues discussed
Whether issue was resolved

Call End (REQUIRED at end of every call)

Save context for next call:

POST /v1/calls/end
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "call_id": "call_123",
  "customer_ref": "customer_123",
  "variables": {
    "name": "John Smith",
    "email": "user@example.com",
    "account_balance": "1234",
    "preferences": "{}"
  },
  "intent": "billing_inquiry",
  "intent_is_open": false
}

Intent Management

Mark intent_is_open:

true if customer needs follow-up (issue unresolved, callback scheduled, etc.)
false if issue was resolved this call

Open intents appear in future calls for continuity.

Error Handling

401 Unauthorized: Check API key configuration
402 Payment Required: Inform customer of technical issue, escalate
429 Too Many Requests: Wait 60s and retry
500 Server Error: Proceed without context, log error

Best Practices

Always call /calls/start BEFORE greeting
Always call /calls/end AFTER call completes
Save everything meaningful to variables
Use consistent customer_ref for same customer
Never expose confidence scores to customers
Use unique call_id (timestamp + random suffix recommended)

Example Flow

Call Start Response:

{
  "call_id": "call_20260201_100000",
  "customer_ref": "cust_jane",
  "call_start": "2026-02-01T10:00:00.000Z",
  "identity": {
    "confidence": 0.85,
    "level": "high",
    "sources": ["ani:mobile", "external_id"],
    "recommendation": "reuse"
  },
  "open_intents": [{
    "intent": "refund_request",
    "status": "open",
    "attempt_count": 1
  }],
  "variables": {
    "name": { "value": "Jane Smith", "source": null, "ttl_seconds": 2592000 },
    "vip": { "value": "true", "source": null, "ttl_seconds": 2592000 }
  }
}

Your Greeting: "Welcome back, Jane! I see you're a VIP customer. I also noticed you called about a refund request recently. I'd be happy to help you with that. Has that been resolved, or would you like me to look into it?"

Call End:

{
  "call_id": "call_20260201_100000",
  "customer_ref": "cust_jane",
  "variables": {
    "name": "Jane Smith",
    "vip": "true",
    "refund_processed": "2026-02-01"
  },
  "intent": "refund_request",
  "intent_is_open": false
}

**📥 Download:** [chatgpt-system-prompt.md](/downloads/chatgpt-system-prompt.md)

---

### Generic LLM System Prompt

SYSTEM: You are a customer service AI agent with Sticky Calls integration for caller context memory.

CREDENTIALS:

API_KEY: YOUR_API_KEY
API_URL: https://api.stickycalls.com

CALL START PROCEDURE:

Receive: call_id, ani (phone number), optional external_ids
Call: POST /v1/calls/start with Authorization: Bearer YOUR_API_KEY
Request body: {"call_id": "call_123", "identity_hints": {"ani": "+14155551234", "external_ids": {}}}
Parse response:
- If identity.confidence >= 0.5: Greet by name, use context
- If identity.confidence 0.3-0.5: Confirm identity
- If identity.confidence < 0.3 or null: Treat as new customer

GREETING TEMPLATES:

High confidence (>=0.7): "Welcome back, name!"
Medium confidence (0.5-0.7): "Hello name, great to hear from you!"
Low confidence (0.3-0.5): "Hello! Could you confirm your name?"
No match (<0.3): "Hello! May I have your name?"

OPEN INTENTS:

If open_intents present: Reference proactively
Example: "I see you called about billing inquiry on Jan 28. Would you like to discuss that?"

CALL END PROCEDURE:

Call: POST /v1/calls/end with same call_id
Include:
- customer_ref (from start response or new)
- variables: All collected info (name, email, account_balance, etc.)
- intent: Primary topic discussed
- intent_is_open: true if unresolved, false if resolved
- external_ids: Any IDs mentioned

VARIABLES TO SAVE:

Customer name
Contact information (email, alternate phone)
Account details (balance, ID, status)
Preferences (language, callback time, communication method)
Issue details
Any commitments made (callback scheduled, refund promised, etc.)

ERROR HANDLING:

401: Invalid API key - alert admin
402: Insufficient credits - escalate
429: Rate limit - wait 60s, retry
500: Server error - proceed without context

RULES:

ALWAYS call /calls/start before greeting
ALWAYS call /calls/end after call concludes
NEVER expose confidence scores to customers
NEVER skip saving context
Use call_id format: call_1234567890_abc123
Reuse customer_ref for same customer

EXAMPLE: Input: call_id="call_123", ani="+14155551234" API Response: {"match": {"customer_ref": "cust_john", "variables": {"name": "John"}}, "confidence": 0.8} Your Greeting: "Welcome back, John! What can I help you with today!"

**📥 Download:** [generic-llm-prompt.txt](/downloads/generic-llm-prompt.txt)

---

## Complete Integration Example

### Scenario: Returning Customer with Billing Issue

**1. Call Arrives**

Input from phone system:

call_id: "call_20260201_150000_abc"
ani: "+14155551234"
crm_id: "crm_12345"

**2. Agent Calls /calls/start**
```http
POST /v1/calls/start HTTP/1.1
Host: api.stickycalls.com
Authorization: Bearer sk_prod_your_key_here
Content-Type: application/json

{
  "call_id": "call_20260201_150000_abc",
  "identity_hints": {
    "ani": "+14155551234",
    "external_ids": {
      "crm_id": "crm_12345"
    }
  }
}

3. API Response

{
  "call_id": "call_20260201_150000_abc",
  "customer_ref": "cust_johndoe",
  "call_start": "2026-02-01T15:00:00.000Z",
  "identity": {
    "confidence": 0.9,
    "level": "very_high",
    "sources": ["ani:mobile", "external_id", "recency:1day"],
    "recommendation": "reuse"
  },
  "open_intents": [
    {
      "intent": "billing_dispute",
      "status": "open",
      "attempt_count": 2
    }
  ],
  "variables": {
    "name": {
      "value": "John Doe",
      "source": null,
      "ttl_seconds": 2592000
    },
    "account_balance": {
      "value": "$1,234.56",
      "source": null,
      "ttl_seconds": 2592000
    },
    "preferred_language": {
      "value": "English",
      "source": null,
      "ttl_seconds": 2592000
    },
    "vip_status": {
      "value": "Gold",
      "source": null,
      "ttl_seconds": 2592000
    }
  }
}

4. Agent Greeting

"Welcome back, John! Great to hear from you again. I see you're a Gold VIP member,
and I noticed you called a couple of times about a billing dispute. I'd be happy
to help resolve that for you today. Your current account balance is $1,234.56.
What can I help you with?"

5. Conversation Happens

Agent collects:
- Issue was duplicate charge of $45.99
- Refund processed successfully
- Customer satisfied
- Updated account balance: $1,188.57

6. Agent Calls /calls/end

POST /v1/calls/end HTTP/1.1
Host: api.stickycalls.com
Authorization: Bearer sk_prod_your_key_here
Content-Type: application/json

{
  "call_id": "call_20260201_150000_abc",
  "customer_ref": "cust_johndoe",
  "intent": "billing_dispute",
  "intent_status": "resolved",
  "variables": {
    "name": "John Doe",
    "account_balance": "$1,188.57",
    "preferred_language": "English",
    "vip_status": "Gold",
    "last_interaction_date": "2026-02-01",
    "last_interaction_summary": "Resolved billing dispute - refunded $45.99 duplicate charge"
  }
}

7. API Response

{
  "call_id": "call_20260201_150000_abc",
  "customer_ref": "cust_johndoe",
  "call_start": "2026-02-01T15:00:00.000Z",
  "call_end": "2026-02-01T15:04:05.000Z",
  "duration_seconds": 245,
  "intents_updated": 1,
  "variables_updated": 6
}

8. Next Call (7 days later)

When John calls back, the agent will see:

All saved variables (updated account balance, last interaction summary)
Closed billing_dispute intent (resolved)
High confidence match (recent interaction + external ID)

Integration Checklist for AI Agents

Setup

Store API key securely in environment variable
Add system prompt to agent configuration
Test API connectivity with /v1/health endpoint
Verify authentication with test API call

Call Start

Call /calls/start BEFORE greeting customer
Parse confidence score and recommendation
Load customer context (variables, open_intents)
Personalize greeting based on confidence level
Proactively reference open intents

During Call

Collect customer name if new
Collect meaningful information (account details, preferences)
Track primary intent/topic
Determine if issue will be resolved

Call End

Call /calls/end with same call_id
Save all collected variables
Set intent and intent_is_open correctly
Include external_ids if collected
Use same customer_ref for returning customers

Error Handling

Handle 401 (invalid API key) gracefully
Handle 402 (insufficient credits) gracefully
Handle 429 (rate limit) with retry logic
Handle 500 (server error) by proceeding without context
Log all errors for debugging

Best Practices

Never expose confidence scores to customers
Use unique call_id for each call (timestamp + random)
Save everything meaningful to variables
Mark intents open=true only if truly unresolved
Reference context naturally (don't sound robotic)

Testing Your Integration

Test Scenarios

1. New Customer (No Match)

curl -X POST https://api.stickycalls.com/v1/calls/start \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "test_new_customer_001",
    "identity_hints": {
      "ani": "+19999999999"
    }
  }'

# Expected: identity.confidence: 0, open_intents: [], variables: {}
# Agent should greet as new customer

2. Returning Customer (High Confidence)

# First call - create context
curl -X POST https://api.stickycalls.com/v1/calls/start \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"call_id": "test_001", "identity_hints": {"ani": "+14155551234"}}'

curl -X POST https://api.stickycalls.com/v1/calls/end \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "test_001",
    "customer_ref": "cust_test",
    "intent": "test",
    "intent_status": "resolved",
    "variables": {"name": "Test User"}
  }'

# Second call - should match
curl -X POST https://api.stickycalls.com/v1/calls/start \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"call_id": "test_002", "identity_hints": {"ani": "+14155551234"}}'

# Expected: customer_ref="cust_test", identity.confidence &gt;= 0.3
# Agent should greet by name

3. Open Intent Follow-up

# Create call with open intent
curl -X POST https://api.stickycalls.com/v1/calls/end \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "test_003",
    "customer_ref": "cust_test",
    "intent": "refund_request",
    "intent_status": "open"
  }'

# Next call should show open intent
curl -X POST https://api.stickycalls.com/v1/calls/start \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"call_id": "test_004", "identity_hints": {"ani": "+14155551234"}}'

# Expected: open_intents array with intent: "refund_request", status: "open"
# Agent should ask about it proactively

API Reference (Quick)

See openapi.yaml for complete machine-readable specification.

POST /v1/calls/start

Request:

{
  "call_id": "unique_id",
  "identity_hints": {
    "ani": "+14155551234",
    "external_ids": {"crm_id": "crm_123"}
  }
}

Response (Match Found):

{
  "call_id": "unique_id",
  "customer_ref": "cust_xxx",
  "call_start": "2026-02-07T10:00:00.000Z",
  "identity": {
    "confidence": 0.8,
    "level": "high",
    "sources": ["ani:mobile", "external_id"],
    "recommendation": "reuse"
  },
  "open_intents": [],
  "variables": {
    "name": {
      "value": "John",
      "source": null,
      "ttl_seconds": 2592000
    }
  }
}

POST /v1/calls/end

Request:

{
  "call_id": "same_unique_id",
  "customer_ref": "cust_xxx",
  "intent": "billing",
  "intent_status": "resolved",
  "variables": {"name": "John", "email": "john@example.com"}
}

Response:

{
  "call_id": "same_unique_id",
  "customer_ref": "cust_xxx",
  "call_start": "2026-02-07T10:00:00.000Z",
  "call_end": "2026-02-07T10:02:00.000Z",
  "duration_seconds": 120,
  "intents_updated": 1,
  "variables_updated": 2
}

Support

Documentation: https://github.com/n8peace/stickycalls/tree/master/docs OpenAPI Spec: openapi.yaml Email: nate@bananaintelligence.ai

For AI Agents: All necessary information is in this document and the OpenAPI spec. You can integrate autonomously.

Overview​

Quick Start for AI Agents​

1. Download System Prompt​

2. Configure API Access​

3. Call Flow​

System Prompts​

Claude System Prompt​

ChatGPT System Prompt​

Interpreting Response​

If match found (confidence >= 0.5)​

If low confidence (0.3 <= confidence < 0.5)​

If no match (confidence < 0.3 or null)​

During Call​

Call End (REQUIRED at end of every call)​

Intent Management​

Error Handling​

Best Practices​

Example Flow​

Integration Checklist for AI Agents​

Setup​

Call Start​

During Call​

Call End​

Error Handling​

Best Practices​

Testing Your Integration​

Test Scenarios​

API Reference (Quick)​

POST /v1/calls/start​

POST /v1/calls/end​

Support​

Overview

Quick Start for AI Agents

1. Download System Prompt

2. Configure API Access

3. Call Flow

System Prompts

Claude System Prompt

ChatGPT System Prompt

Interpreting Response

If match found (confidence >= 0.5)

If low confidence (0.3 <= confidence < 0.5)

If no match (confidence < 0.3 or null)

During Call

Call End (REQUIRED at end of every call)

Intent Management

Error Handling

Best Practices

Example Flow

Integration Checklist for AI Agents

Setup

Call Start

During Call

Call End

Error Handling

Best Practices

Testing Your Integration

Test Scenarios

API Reference (Quick)

POST /v1/calls/start

POST /v1/calls/end

Support