thisispamela 1.0.1

Pamela Enterprise Voice API SDK for Python

thisispamela SDK for Python

Official SDK for the Pamela Enterprise Voice API.

Installation

pip install thisispamela

Usage

Basic Example

from pamela import PamelaClient

client = PamelaClient(
    api_key="pk_live_your_api_key_here",
    base_url="https://api.thisispamela.com",  # Optional
)

# Create a call
call = client.create_call(
    to="[phone]",
    task="Order a large pizza for delivery",
    locale="en-US",
)

print(f"Call created: {call['id']}")

# Get call status
status = client.get_call(call["id"])
print(f"Call status: {status['status']}")

Webhook Verification

from flask import Flask, request
from pamela import verify_webhook_signature

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route("/webhooks/pamela", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Pamela-Signature")
    payload = request.json

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    # Handle webhook event
    print(f"Webhook event: {payload['event']}")
    print(f"Call ID: {payload['call_id']}")

    return {"status": "ok"}, 200

Tool Webhook Handler

from flask import Flask, request
from pamela import verify_webhook_signature

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route("/webhooks/pamela/tools", methods=["POST"])
def handle_tool_webhook():
    signature = request.headers.get("X-Pamela-Signature")
    payload = request.json

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    tool_name = payload["tool_name"]
    arguments = payload["arguments"]
    call_id = payload["call_id"]
    correlation_id = payload["correlation_id"]

    # Execute tool based on tool_name
    if tool_name == "check_order_status":
        order_id = arguments.get("order_id")
        result = check_order_status(order_id)
        return {"result": result}

    return {"error": "Unknown tool"}, 400

Getting API Keys

Obtaining Your API Key

API keys are created and managed through the Pamela Partner Portal or via the Partner API:

1. Sign up for an Enterprise subscription (see Subscription Requirements below)
2. Create an API key via one of these methods:
   • Partner Portal: Log in to your account and navigate to the Enterprise panel
   • Partner API: POST /api/b2b/v1/partner/api-keys

     curl -X POST https://api.thisispamela.com/api/b2b/v1/partner/api-keys \
       -H "Authorization: Bearer YOUR_B2C_USER_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"project_id": "optional-project-id", "key_prefix": "pk_live_"}'
     

3. Save your API key immediately - the full key is only returned once during creation
4. Use the key prefix (pk_live_ or pk_test_) to identify keys in your account

Managing API Keys

• List API keys: GET /api/b2b/v1/partner/api-keys
• Revoke API key: POST /api/b2b/v1/partner/api-keys/{key_id}/revoke
• Associate with projects: Optionally link API keys to specific projects for better organization

API Key Format

• Live keys: Start with pk_live_ (for production use)
• Test keys: Start with pk_test_ (for development/testing)
• Security: Keys are hashed in the database. Store them securely and never commit them to version control.

Subscription Requirements

Enterprise Subscription Required

All API access requires an active Enterprise subscription. API calls will return 403 Forbidden if:

• No Enterprise subscription is active
• Subscription status is past_due and grace period has expired
• Subscription status is canceled

Grace Period

Enterprise subscriptions have a 1-week grace period when payment fails:

• During grace period: API access is allowed, but usage is still charged
• After grace period expires: API access is blocked until payment is updated

Subscription Status Endpoints

Check subscription status using the Enterprise Partner API:

• GET /api/b2b/v1/partner/subscription - Get subscription status
• POST /api/b2b/v1/partner/subscription/checkout - Create checkout session
• POST /api/b2b/v1/partner/subscription/portal - Access Customer Portal

Error Codes

Authentication Errors

• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Subscription inactive or expired
  • Check subscription status: subscription_status must be "active"
  • For past_due: Check grace_period_ends_at - access allowed during grace period

Validation Errors

• 400 Bad Request: Invalid request parameters
• 404 Not Found: Resource not found (call, partner, etc.)

Quota/Limit Errors

• 429 Too Many Requests: Quota exceeded (if quota limits are set)
• Note: Enterprise subscriptions have no quota limits for API calls (all usage is billed per-minute)

Rate Limit Errors

• 429 Too Many Requests: Rate limit exceeded
• Retry after the time specified in Retry-After header

Usage Limits & Billing

Enterprise API Usage

• Unlimited API calls (no call count limits)
• All API usage billed at $0.10/minute (10 cents per minute)
• Minimum billing: 1 minute per call (even if call duration < 60 seconds)
• Billing calculation: billed_minutes = max(ceil(duration_seconds / 60), 1)
• Only calls that connect (have started_at) are billed

Usage Tracking

• Usage is tracked in b2b_usage collection with type: "api_usage" (collection name stays b2b_usage)
• Usage is synced to Stripe hourly (at :00 minutes)
• Stripe meter name: stripe_minutes
• Failed syncs are retried with exponential backoff (1s, 2s, 4s, 8s, 16s), max 5 retries

Billing Period

• Billing is based on calendar months (UTC midnight on 1st of each month)
• Calls are billed in the month where started_at occurred
• Usage sync status: pending, synced, or failed

API Methods

Calls

• create_call(to, task, ...) - Create a new call
• get_call(call_id) - Get call status and details
• list_calls(status?, limit?, offset?, ...) - List calls with optional filters
• cancel_call(call_id) - Cancel an in-progress call

Tools

• register_tool(name, description, input_schema, ...) - Register a tool
• list_tools() - List all tools
• delete_tool(tool_id) - Delete a tool

Usage

• usage.get(period=None) - Get usage statistics

Example:

# Get current month usage
usage = client.usage.get()

# Get usage for specific period
jan_usage = client.usage.get("2024-01")

print(f"Usage: {usage['call_count']} calls, {usage.get('api_minutes', 0)} minutes")
print(f"Quota: {usage.get('quota', {}).get('partner_limit', 'Unlimited')}")

Response:

{
    "partner_id": "partner_123",
    "project_id": "project_456",  # Optional
    "period": "2024-01",
    "call_count": 150,
    "quota": {
        "partner_limit": None,  # None = unlimited for Enterprise
        "project_limit": None
    }
}

Note: Enterprise subscriptions have no quota limits - all usage is billed per-minute.

API Reference

See the Pamela Enterprise API Documentation for full API reference.