TalkTool API

{
  "error": {
    "code": "invalid_request",
    "message": "phone is not a valid phone number. Use E.164, e.g. +13105551234",
    "request_id": "6b0f1c6e-3a52-4a0e-9f0e-1d2c3b4a5f60",
    "details": { "field": "phone" }
  }
}

curl -X POST https://www.usetalktool.com/api/v1/contacts \
  -H "Authorization: Bearer $TALKTOOL_API_KEY" \
  -H "Idempotency-Key: crm-sync-8841-v1" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Maria","phone":"+13105551234"}'

curl "https://www.usetalktool.com/api/v1/calls?direction=inbound&since=2026-10-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer $TALKTOOL_API_KEY"

curl https://www.usetalktool.com/api/v1/calls/CA1f2e3d4c5b6a79880011223344556677 \
  -H "Authorization: Bearer $TALKTOOL_API_KEY"

{
  "data": {
    "id": "CA1f2e3d4c5b6a79880011223344556677",
    "direction": "outbound",
    "status": "completed",
    "type": "call",
    "from": "+13105550100",
    "to": "+13105551234",
    "number": "+13105550100",
    "contact": {
      "id": "66f1c2a9b7d4e5a1c8f03a12",
      "first_name": "Maria",
      "last_name": "Gonzalez",
      "external_id": "crm_8841"
    },
    "started_at": "2026-10-14T18:00:02.000Z",
    "answered_at": "2026-10-14T18:00:09.000Z",
    "ended_at": "2026-10-14T18:04:41.000Z",
    "duration_seconds": 279,
    "languages": { "agent": "EN_US", "customer": "ES_US" },
    "transcript_text": "Agent: Hello, this is Sam from Acme...",
    "summary": {
      "text": "Sam confirmed Maria's appointment for Friday.",
      "key_points": ["Appointment confirmed for Friday 10am"],
      "action_items": ["Send reminder text on Thursday"],
      "sentiment": "positive"
    },
    "recording": {
      "available": true,
      "url": "https://www.usetalktool.com/api/v1/calls/CA1f2e3d4c5b6a79880011223344556677/recording"
    },
    "created_at": "2026-10-14T18:00:02.000Z",
    "updated_at": "2026-10-14T18:05:10.000Z"
  }
}

curl -L https://www.usetalktool.com/api/v1/calls/CA1f2e3d4c5b6a79880011223344556677/recording \
  -H "Authorization: Bearer $TALKTOOL_API_KEY" \
  -o call-recording.mp3

POST /talktool/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: TalkTool-Webhooks/1.0
TalkTool-Event-Id: evt_5b0f1c6e-3a52-4a0e-9f0e-1d2c3b4a5f60
TalkTool-Event-Type: call.completed
TalkTool-Delivery-Attempt: 1
TalkTool-Signature: t=1760465082,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_5b0f1c6e-3a52-4a0e-9f0e-1d2c3b4a5f60",
  "type": "call.completed",
  "api_version": "2026-10-15",
  "created_at": "2026-10-14T18:04:42.000Z",
  "data": {
    "call": {
      "id": "CA1f2e3d4c5b6a79880011223344556677",
      "direction": "outbound",
      "status": "completed",
      "type": "call",
      "from": "+13105550100",
      "to": "+13105551234",
      "number": "+13105550100",
      "contact": {
        "id": "66f1c2a9b7d4e5a1c8f03a12",
        "first_name": "Maria",
        "last_name": "Gonzalez",
        "external_id": "crm_8841"
      },
      "started_at": "2026-10-14T18:00:02.000Z",
      "answered_at": "2026-10-14T18:00:09.000Z",
      "ended_at": "2026-10-14T18:04:41.000Z",
      "duration_seconds": 279,
      "languages": { "agent": "EN_US", "customer": "ES_US" },
      "transcript_text": null,
      "summary": null,
      "recording": { "available": false, "url": null },
      "created_at": "2026-10-14T18:00:02.000Z",
      "updated_at": "2026-10-14T18:04:41.000Z"
    }
  }
}

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.TALKTOOL_WEBHOOK_SECRET; // whsec_...

function verify(rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.trim().split(/=(.*)/s).slice(0, 2))
  );
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(parts.t + "." + rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Use the RAW body. Parsing and re-serializing JSON changes the bytes.
app.post("/talktool/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("TalkTool-Signature") || "")) {
    return res.status(400).send("bad signature");
  }
  res.sendStatus(200); // acknowledge first, work later
  const event = JSON.parse(raw);
  queue.add(event); // dedupe on event.id inside your worker
});

import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["TALKTOOL_WEBHOOK_SECRET"].encode()  # whsec_...


def verify(raw_body: bytes, header: str, tolerance_sec: int = 300) -> bool:
    try:
        parts = dict(p.strip().split("=", 1) for p in header.split(","))
        timestamp = parts["t"]
        signature = parts["v1"]
        if abs(time.time() - int(timestamp)) > tolerance_sec:
            return False
    except (KeyError, ValueError):
        return False
    expected = hmac.new(
        SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/talktool/webhooks")
def talktool_webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not verify(raw, request.headers.get("TalkTool-Signature", "")):
        return "bad signature", 400
    enqueue(request.get_json())  # dedupe on event["id"] in your worker
    return "", 200