{"meta":{"title":"Wiretalk Public API","version":"v1","base_url":"https:\/\/wiretalk.tech\/api\/v1","content_type":"application\/json","rate_limit_per_minute":120,"key_prefix":"wt_live_"},"authentication":{"summary":"All requests require an organization API key.","methods":[{"name":"Authorization header (recommended)","example":"Authorization: Bearer wt_live_xxxxxxxx"},{"name":"X-Wiretalk-Key header","example":"X-Wiretalk-Key: wt_live_xxxxxxxx"}],"notes":["Create API keys from Team & Organization \u2192 API keys in the agent dashboard.","Keys are shown only once when created. Store them securely.","Each key has scoped permissions (abilities). Requests without the required ability return 403."]},"abilities":[{"key":"conversations:read","label":"Read conversations and messages"},{"key":"conversations:write","label":"Send messages and close conversations"},{"key":"visitors:read","label":"Read visitors"},{"key":"tickets:read","label":"Read tickets"},{"key":"tickets:write","label":"Create and update tickets"}],"endpoints":[{"group":"Account","items":[{"method":"GET","path":"\/me","ability":null,"summary":"Get organization and API key context","query":[],"body":null,"response":"{\n    \"organization\": {\n        \"id\": 1,\n        \"name\": \"Acme Inc\",\n        \"plan\": \"pro\"\n    },\n    \"api_key\": {\n        \"id\": 3,\n        \"name\": \"CRM integration\",\n        \"key_prefix\": \"wt_live_abcd1234\",\n        \"abilities\": [\n            \"conversations:read\",\n            \"visitors:read\"\n        ],\n        \"last_used_at\": \"2026-07-07T10:00:00+00:00\"\n    }\n}","status":200}]},{"group":"Conversations","items":[{"method":"GET","path":"\/conversations","ability":"conversations:read","summary":"List visitor conversations for your organization","query":[{"name":"status","type":"string","description":"Filter by status: waiting, active, closed, missed"},{"name":"site_id","type":"integer","description":"Filter by website ID"},{"name":"page","type":"integer","description":"Page number (default 1)"},{"name":"per_page","type":"integer","description":"Results per page (max 100, default 50)"}],"body":null,"response":"{\n    \"data\": [\n        {\n            \"id\": 42,\n            \"site_id\": 1,\n            \"visitor_id\": 9,\n            \"status\": \"active\",\n            \"type\": \"visitor\",\n            \"locale\": \"en\",\n            \"assigned_agent_id\": 2,\n            \"started_at\": \"2026-07-07T09:00:00+00:00\",\n            \"visitor\": {\n                \"id\": 9,\n                \"name\": \"Jane\",\n                \"email\": \"jane@example.com\"\n            }\n        }\n    ],\n    \"current_page\": 1,\n    \"per_page\": 50\n}","status":200},{"method":"GET","path":"\/conversations\/{conversation}","ability":"conversations:read","summary":"Get a conversation with all messages","query":[],"body":null,"response":"{\n    \"id\": 42,\n    \"status\": \"active\",\n    \"messages\": [\n        {\n            \"id\": 101,\n            \"body\": \"Hello, I need help\",\n            \"type\": \"text\",\n            \"sender_type\": \"visitor\",\n            \"created_at\": \"2026-07-07T09:01:00+00:00\",\n            \"attachments\": []\n        }\n    ]\n}","status":200},{"method":"GET","path":"\/conversations\/{conversation}\/messages","ability":"conversations:read","summary":"List messages in a conversation (paginated, newest first)","query":[{"name":"page","type":"integer","description":"Page number"},{"name":"per_page","type":"integer","description":"Results per page (max 100)"}],"body":null,"response":"{\n    \"data\": [\n        {\n            \"id\": 101,\n            \"body\": \"Hello\",\n            \"sender_type\": \"visitor\"\n        }\n    ]\n}","status":200},{"method":"POST","path":"\/conversations\/{conversation}\/messages","ability":"conversations:write","summary":"Send an agent reply to a visitor conversation","query":[],"body":[{"name":"body","type":"string","required":true,"description":"Message text (max 5000 chars)"},{"name":"agent_user_id","type":"integer","required":false,"description":"Agent user ID in your organization. Defaults to the user who created the API key."}],"response":"{\n    \"id\": 102,\n    \"body\": \"Thanks for reaching out \u2014 we can help with that.\",\n    \"type\": \"text\",\n    \"sender_type\": \"agent\",\n    \"sender_id\": 2,\n    \"created_at\": \"2026-07-07T09:05:00+00:00\",\n    \"attachments\": []\n}","status":201},{"method":"POST","path":"\/conversations\/{conversation}\/close","ability":"conversations:write","summary":"Close a visitor conversation","query":[],"body":[{"name":"agent_user_id","type":"integer","required":false,"description":"Agent user ID performing the close action"}],"response":"{\n    \"id\": 42,\n    \"status\": \"closed\",\n    \"closed_at\": \"2026-07-07T09:10:00+00:00\"\n}","status":200}]},{"group":"Visitors","items":[{"method":"GET","path":"\/visitors","ability":"visitors:read","summary":"List visitors across your websites","query":[{"name":"search","type":"string","description":"Search name, email, or visitor UID"},{"name":"site_id","type":"integer","description":"Filter by website ID"},{"name":"page","type":"integer","description":"Page number"},{"name":"per_page","type":"integer","description":"Results per page (max 100)"}],"body":null,"response":"{\n    \"data\": [\n        {\n            \"id\": 9,\n            \"visitor_uid\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n            \"site_id\": 1,\n            \"name\": \"Jane Doe\",\n            \"email\": \"jane@example.com\",\n            \"country\": \"IN\",\n            \"language\": \"en\",\n            \"last_seen_at\": \"2026-07-07T09:00:00+00:00\"\n        }\n    ]\n}","status":200},{"method":"GET","path":"\/visitors\/{visitor}","ability":"visitors:read","summary":"Get visitor profile and activity counts","query":[],"body":null,"response":"{\n    \"id\": 9,\n    \"name\": \"Jane Doe\",\n    \"email\": \"jane@example.com\",\n    \"conversations_count\": 3,\n    \"tickets_count\": 1\n}","status":200}]},{"group":"Tickets","items":[{"method":"GET","path":"\/tickets","ability":"tickets:read","summary":"List support tickets","query":[{"name":"status","type":"string","description":"open, pending, in_progress, resolved, closed"},{"name":"priority","type":"string","description":"low, normal, high, urgent"},{"name":"page","type":"integer","description":"Page number"},{"name":"per_page","type":"integer","description":"Results per page (max 100)"}],"body":null,"response":"{\n    \"data\": [\n        {\n            \"id\": 7,\n            \"ticket_number\": \"TKT-2026-00007\",\n            \"subject\": \"Billing question\",\n            \"status\": \"open\",\n            \"priority\": \"normal\",\n            \"source\": \"widget\"\n        }\n    ]\n}","status":200},{"method":"GET","path":"\/tickets\/{ticket}","ability":"tickets:read","summary":"Get ticket details with comments","query":[],"body":null,"response":"{\n    \"id\": 7,\n    \"ticket_number\": \"TKT-2026-00007\",\n    \"subject\": \"Billing question\",\n    \"status\": \"open\",\n    \"comments\": [\n        {\n            \"id\": 1,\n            \"body\": \"I was charged twice.\",\n            \"is_internal\": false,\n            \"created_at\": \"2026-07-07T08:00:00+00:00\"\n        }\n    ]\n}","status":200},{"method":"POST","path":"\/tickets","ability":"tickets:write","summary":"Create a new ticket (requires ticketing on your plan)","query":[],"body":[{"name":"subject","type":"string","required":true,"description":"Ticket subject"},{"name":"description","type":"string","required":true,"description":"Initial ticket message"},{"name":"priority","type":"string","required":false,"description":"low, normal, high, urgent (default normal)"},{"name":"site_id","type":"integer","required":false,"description":"Website ID (defaults to first site)"},{"name":"visitor_id","type":"integer","required":false,"description":"Link to an existing visitor"},{"name":"customer_name","type":"string","required":false,"description":"Customer name if no visitor"},{"name":"customer_email","type":"string","required":false,"description":"Customer email if no visitor"}],"response":"{\n    \"id\": 8,\n    \"ticket_number\": \"TKT-2026-00008\",\n    \"subject\": \"API integration\",\n    \"status\": \"open\",\n    \"priority\": \"normal\",\n    \"source\": \"api\"\n}","status":201},{"method":"PATCH","path":"\/tickets\/{ticket}\/status","ability":"tickets:write","summary":"Update ticket status","query":[],"body":[{"name":"status","type":"string","required":true,"description":"open, pending, in_progress, resolved, closed"},{"name":"agent_user_id","type":"integer","required":false,"description":"Agent performing the update"}],"response":"{\n    \"id\": 7,\n    \"status\": \"resolved\"\n}","status":200}]}],"webhooks":{"summary":"Outgoing webhooks push real-time events to your HTTPS endpoints.","configure":"Team & Organization \u2192 Outgoing webhooks","delivery":{"method":"POST","content_type":"application\/json","headers":{"X-Wiretalk-Event":"Event name (e.g. message.received)","X-Wiretalk-Delivery":"Unique delivery UUID","X-Wiretalk-Signature":"HMAC SHA-256 of raw body when a signing secret is set"}},"payload":"{\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"event\": \"message.received\",\n    \"created_at\": \"2026-07-07T09:01:00+00:00\",\n    \"data\": {\n        \"conversation_id\": 42,\n        \"site_id\": 1,\n        \"organization_id\": 1,\n        \"message\": {\n            \"id\": 101,\n            \"body\": \"Hello\",\n            \"type\": \"text\"\n        }\n    }\n}","events":[{"key":"conversation.started","label":"conversation.started","description":"","feature":""},{"key":"message.received","label":"message.received","description":"","feature":""},{"key":"message.sent","label":"message.sent","description":"","feature":""},{"key":"chat.missed","label":"chat.missed","description":"","feature":""},{"key":"ticket.created","label":"ticket.created","description":"","feature":""},{"key":"ticket.assigned","label":"ticket.assigned","description":"","feature":""},{"key":"ticket.status_changed","label":"ticket.status_changed","description":"","feature":""},{"key":"ticket.priority_changed","label":"ticket.priority_changed","description":"","feature":""},{"key":"ticket.comment_added","label":"ticket.comment_added","description":"","feature":""},{"key":"chat.closed","label":"chat.closed","description":"","feature":""},{"key":"review.submitted","label":"review.submitted","description":"","feature":""}],"verify_signature":"signature = HMAC_SHA256(raw_json_body, signing_secret)"},"errors":[{"code":401,"meaning":"Missing or invalid API key"},{"code":403,"meaning":"API key lacks required ability or plan feature"},{"code":404,"meaning":"Resource not found or not in your organization"},{"code":422,"meaning":"Validation error or missing agent_user_id for write actions"},{"code":429,"meaning":"Rate limit exceeded"}],"openapi_url":"https:\/\/wiretalk.tech\/docs\/api\/openapi.json"}