TringTring AI

    TringTring.AI – Zapier Integration (Public API Guide)

    This guide describes the public HTTP interface used by Zapier to integrate with TringTring.AI. It covers authentication, the REST Hook trigger (call_disposition), and the action (initiate outbound call). Use it to configure the Zapier Platform UI and for manual testing.

    Important

    • Treat all keys and secrets as confidential. Do not embed them in client-side code.
    • All endpoints require HTTPS.

    Authentication

    API Key authentication with optional agent credential verification.

    Headers

    • X-API-Key: <api_key>
      • Alternative: Authorization: Bearer <api_key>

    Auth Test Endpoint

    • Method: GET
    • URL: https://{SERVER_URL}/api/zapier/auth/test
    • Headers: X-API-Key: <api_key>
    • Optional agent verification:
      • Query params: agent_id=<uuid>&agent_secret=<string>
      • OR headers: X-Agent-Id: <uuid>, X-Agent-Secret: <string>

    Responses

    • 200 {"ok": true}
    • 401 {"ok": false, "error": "agent_id and agent_secret required"} (if one is missing when provided)
    • 404 {"ok": false, "error": "agent not found"}
    • 401 {"ok": false, "error": "invalid agent credentials"}

    Trigger: call_disposition (REST Hook)

    Notifies Zapier when a call completes. Scope is by agent_id.

    Subscribe

    • Method: POST
    • URL: https://{SERVER_URL}/api/zapier/subscribe/call-completed
    • Headers: X-API-Key: <api_key>, Content-Type: application/json
    • Body (JSON or query params supported):
      • agent_id (string, required): Agent to scope the subscription
      • agent_secret (string, required): Credential for validation
      • callback_url OR target_url (string, required): Zapier’s webhook URL

    Example (Subscribe)

    curl -X POST "https://{SERVER_URL}/api/zapier/subscribe/call-completed" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_uuid>",
    "agent_secret": "<agent_secret>",
    "callback_url": "https://hooks.zapier.com/hooks/standard/123/abc"
  }'

    Response (201)

    {
  "id": "<subscription_uuid>",
  "agent_id": "<agent_uuid>",
  "trigger_key": "call_disposition",
  "callback_url": "https://hooks.zapier.com/hooks/standard/123/abc",
  "created_at": "2025-01-01T00:00:00Z"
}

    Unsubscribe

    • Method: DELETE
    • URL: https://{SERVER_URL}/api/zapier/unsubscribe/{subscription_id}
    • Headers: X-API-Key: <api_key>

    Perform List (Editor Sample)

    • Method: GET
    • URL: https://{SERVER_URL}/api/zapier/samples/call-disposition
    • Headers: X-API-Key: <api_key>
    • Returns a JSON array for Zapier’s “Test trigger” UI.

    Example (Perform List)

    curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://{SERVER_URL}/api/zapier/samples/call-disposition"

    Event Delivery (Webhook → Zapier)

    • On call completion, TringTring.AI posts a payload to each enabled subscriber for the matching agent_id:

    Current Payload

    {
  "call_id": "<uuid>",
  "agent_id": "<uuid>",
  "campaign_id": "<uuid | null>",
  "status": "completed | busy | failed | voicemail"
}

    Notes

    • Additional fields may be added in the future. Ignore unknown fields.
    • Delivery is scoped by agent_id.

    Common Errors

    • 400 {"error": "agent_id, agent_secret and callback_url (or target_url) are required"}
    • 401 {"error": "invalid agent credentials"}
    • 404 {"error": "agent not found"}

    Action: Initiate Outbound Call

    Initiates an outbound call using the provided phone numbers and agent context.

    Endpoint

    • Method: POST
    • URL: https://{SERVER_URL}/api/zapier/actions/outbound-call
    • Headers: X-API-Key: <api_key>, Content-Type: application/json
    • Body: JSON (query params are also supported)

    Request Parameters

    • agent_id (string, required)
    • to_number (string, required, E.164 recommended)
    • from_number (string, optional)
      • If omitted, the system uses the agent’s default_number when configured. If neither is available, request fails with 400.
    • params (object, optional)
      • Arbitrary key/value pairs to parameterize prompts (e.g., {"customer_name": "John", "city": "Bengaluru"}).
    • call_id (string, optional) – generates a UUID if omitted.

    Example (JSON)

    curl -X POST "https://{SERVER_URL}/api/zapier/actions/outbound-call" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_uuid>",
    "to_number": "+14155550123",
    "from_number": "+14155550100",
    "params": {"customer_name": "John", "city": "Bengaluru"}
  }'

    Example (Query Params)

    curl -X POST \
  "https://{SERVER_URL}/api/zapier/actions/outbound-call?agent_id=<agent_uuid>&to_number=%2B14155550123" \
  -H "X-API-Key: YOUR_API_KEY"

    Responses

    • 200 {"success": true, "call_id": "<uuid>"}
    • 400 {"error": "Missing required: agent_id, to_number"}
    • 400 {"error": "from_number missing and agent has no default_number"}
    • 401 {"error": "Missing API key"} or {"detail": "Invalid API key"}
    • 404 {"error": "agent not found"}
    • 500 {"error": "Failed to initiate outbound call", "details": "..."}

    Behavior

    • If from_number is not provided, the system attempts to use the agent’s default_number.
    • params may be provided as a JSON object; if a UI sends it as a string, the API attempts JSON parsing and falls back to an empty object on failure.

    Zapier Platform UI Configuration (Reference)

    Trigger (REST Hook)

    • Subscribe URL: POST https://{SERVER_URL}/api/zapier/subscribe/call-completed
    • Unsubscribe URL: DELETE https://{SERVER_URL}/api/zapier/unsubscribe/{{bundle.subscribeData.id}}
    • Perform List: GET https://{SERVER_URL}/api/zapier/samples/call-disposition
    • Headers (all): X-API-Key: {{bundle.authData.api_key}}
    • Subscribe Body (Code Mode or Form Mode):
    {
  "agent_id": "{{bundle.authData.agent_id}}",
  "agent_secret": "{{bundle.authData.agent_secret}}",
  "callback_url": "{{bundle.targetUrl}}"
}

    Action (Create)

    • API Endpoint: POST https://{SERVER_URL}/api/zapier/actions/outbound-call
    • Headers: X-API-Key: {{bundle.authData.api_key}}, Content-Type: application/json
    • Body (Code Mode):
    {
  "agent_id": "{{bundle.authData.agent_id}}",
  "from_number": "{{bundle.inputData.from_number}}",
  "to_number": "{{bundle.inputData.to_number}}",
  "params": {{bundle.inputData.params}}
}
    • Recommended Input Fields:
      • from_number (required)
      • to_number (required)
      • params (Dictionary; optional)
      • Optional override: agent_id (if users should override the default per-step)

    Notes

    • Test trigger in the editor calls Perform List only. To test live delivery, turn the Zap ON.
    • Ensure X-API-Key is present on all calls.

    Error Handling

    Endpoints return JSON error objects with an HTTP status code.

    Examples

    • 400 (validation): {"error": "Missing required: to_number"}
    • 401 (auth): {"detail": "Invalid API key"}
    • 404 (not found): {"error": "agent not found"}
    • 500 (server): {"error": "Failed to initiate outbound call", "details": "..."}

    Versioning

    • Backward-compatible additions (e.g., new fields in event payloads) may occur without notice. Clients should ignore unknown fields.
    • Breaking changes will be versioned via new endpoints or documented migration notes.