{"openapi":"3.1.0","info":{"title":"Wiretalk Public API","version":"v1","description":"Wiretalk public REST API for conversations, visitors, and tickets. Authenticate with an organization API key via `Authorization: Bearer wt_live_...` or `X-Wiretalk-Key`.","contact":{"name":"Wiretalk","url":"https:\/\/wiretalk.tech\/docs\/api"}},"servers":[{"url":"https:\/\/wiretalk.tech\/api\/v1","description":"API v1 base URL"}],"tags":[{"name":"Account"},{"name":"Conversations"},{"name":"Visitors"},{"name":"Tickets"}],"paths":{"\/me":{"get":{"operationId":"get_me","summary":"Get organization and API key context","tags":["Account"],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"organization":{"id":1,"name":"Acme Inc","plan":"pro"},"api_key":{"id":3,"name":"CRM integration","key_prefix":"wt_live_abcd1234","abilities":["conversations:read","visitors:read"],"last_used_at":"2026-07-07T10:00:00+00:00"}},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/conversations":{"get":{"operationId":"get_conversations","summary":"List visitor conversations for your organization","tags":["Conversations"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status: waiting, active, closed, missed","schema":{"type":"string","enum":["waiting","active","closed","missed"]}},{"name":"site_id","in":"query","required":false,"description":"Filter by website ID","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number (default 1)","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (max 100, default 50)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"data":[{"id":42,"site_id":1,"visitor_id":9,"status":"active","type":"visitor","locale":"en","assigned_agent_id":2,"started_at":"2026-07-07T09:00:00+00:00","visitor":{"id":9,"name":"Jane","email":"jane@example.com"}}],"current_page":1,"per_page":50},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `conversations:read`","x-required-ability":"conversations:read"}},"\/conversations\/{conversation}":{"get":{"operationId":"get_conversations_conversation","summary":"Get a conversation with all messages","tags":["Conversations"],"parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"},"description":"Conversation ID"}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"id":42,"status":"active","messages":[{"id":101,"body":"Hello, I need help","type":"text","sender_type":"visitor","created_at":"2026-07-07T09:01:00+00:00","attachments":[]}]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `conversations:read`","x-required-ability":"conversations:read"}},"\/conversations\/{conversation}\/messages":{"get":{"operationId":"get_conversations_conversation_messages","summary":"List messages in a conversation (paginated, newest first)","tags":["Conversations"],"parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"},"description":"Conversation ID"},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (max 100)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"data":[{"id":101,"body":"Hello","sender_type":"visitor"}]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `conversations:read`","x-required-ability":"conversations:read"},"post":{"operationId":"post_conversations_conversation_messages","summary":"Send an agent reply to a visitor conversation","tags":["Conversations"],"parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"},"description":"Conversation ID"}],"responses":{"201":{"description":"Created","content":{"application\/json":{"example":{"id":102,"body":"Thanks for reaching out \u2014 we can help with that.","type":"text","sender_type":"agent","sender_id":2,"created_at":"2026-07-07T09:05:00+00:00","attachments":[]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `conversations:write`","x-required-ability":"conversations:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Message text (max 5000 chars)"},"agent_user_id":{"type":"integer","description":"Agent user ID in your organization. Defaults to the user who created the API key."}},"required":["body"]}}}}}},"\/conversations\/{conversation}\/close":{"post":{"operationId":"post_conversations_conversation_close","summary":"Close a visitor conversation","tags":["Conversations"],"parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"},"description":"Conversation ID"}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"id":42,"status":"closed","closed_at":"2026-07-07T09:10:00+00:00"},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `conversations:write`","x-required-ability":"conversations:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"agent_user_id":{"type":"integer","description":"Agent user ID performing the close action"}},"required":null}}}}}},"\/visitors":{"get":{"operationId":"get_visitors","summary":"List visitors across your websites","tags":["Visitors"],"parameters":[{"name":"search","in":"query","required":false,"description":"Search name, email, or visitor UID","schema":{"type":"string","enum":["name","email","or"]}},{"name":"site_id","in":"query","required":false,"description":"Filter by website ID","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (max 100)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"data":[{"id":9,"visitor_uid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","site_id":1,"name":"Jane Doe","email":"jane@example.com","country":"IN","language":"en","last_seen_at":"2026-07-07T09:00:00+00:00"}]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `visitors:read`","x-required-ability":"visitors:read"}},"\/visitors\/{visitor}":{"get":{"operationId":"get_visitors_visitor","summary":"Get visitor profile and activity counts","tags":["Visitors"],"parameters":[{"name":"visitor","in":"path","required":true,"schema":{"type":"integer"},"description":"Visitor ID"}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"id":9,"name":"Jane Doe","email":"jane@example.com","conversations_count":3,"tickets_count":1},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `visitors:read`","x-required-ability":"visitors:read"}},"\/tickets":{"get":{"operationId":"get_tickets","summary":"List support tickets","tags":["Tickets"],"parameters":[{"name":"status","in":"query","required":false,"description":"open, pending, in_progress, resolved, closed","schema":{"type":"string","enum":["open","pending","in_progress","resolved","closed"]}},{"name":"priority","in":"query","required":false,"description":"low, normal, high, urgent","schema":{"type":"string","enum":["low","normal","high","urgent"]}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Results per page (max 100)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"data":[{"id":7,"ticket_number":"TKT-2026-00007","subject":"Billing question","status":"open","priority":"normal","source":"widget"}]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `tickets:read`","x-required-ability":"tickets:read"},"post":{"operationId":"post_tickets","summary":"Create a new ticket (requires ticketing on your plan)","tags":["Tickets"],"responses":{"201":{"description":"Created","content":{"application\/json":{"example":{"id":8,"ticket_number":"TKT-2026-00008","subject":"API integration","status":"open","priority":"normal","source":"api"},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `tickets:write`","x-required-ability":"tickets:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"Ticket subject"},"description":{"type":"string","description":"Initial ticket message"},"priority":{"type":"string","description":"low, normal, high, urgent (default normal)","enum":["low","normal","high","urgent"]},"site_id":{"type":"integer","description":"Website ID (defaults to first site)"},"visitor_id":{"type":"integer","description":"Link to an existing visitor"},"customer_name":{"type":"string","description":"Customer name if no visitor"},"customer_email":{"type":"string","description":"Customer email if no visitor"}},"required":["subject","description"]}}}}}},"\/tickets\/{ticket}":{"get":{"operationId":"get_tickets_ticket","summary":"Get ticket details with comments","tags":["Tickets"],"parameters":[{"name":"ticket","in":"path","required":true,"schema":{"type":"integer"},"description":"Ticket ID"}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"id":7,"ticket_number":"TKT-2026-00007","subject":"Billing question","status":"open","comments":[{"id":1,"body":"I was charged twice.","is_internal":false,"created_at":"2026-07-07T08:00:00+00:00"}]},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `tickets:read`","x-required-ability":"tickets:read"}},"\/tickets\/{ticket}\/status":{"patch":{"operationId":"patch_tickets_ticket_status","summary":"Update ticket status","tags":["Tickets"],"parameters":[{"name":"ticket","in":"path","required":true,"schema":{"type":"integer"},"description":"Ticket ID"}],"responses":{"200":{"description":"Successful response","content":{"application\/json":{"example":{"id":7,"status":"resolved"},"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/RateLimited"}},"description":"Required ability: `tickets:write`","x-required-ability":"tickets:write","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"open, pending, in_progress, resolved, closed","enum":["open","pending","in_progress","resolved","closed"]},"agent_user_id":{"type":"integer","description":"Agent performing the update"}},"required":["status"]}}}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Organization API key prefixed with `wt_live_`."},"wiretalkApiKey":{"type":"apiKey","in":"header","name":"X-Wiretalk-Key","description":"Alternative header for the organization API key."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"message":"Unauthenticated."}}}},"Forbidden":{"description":"API key lacks required ability or plan feature","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"message":"API key missing required ability: conversations:read"}}}},"NotFound":{"description":"Resource not found or not in your organization","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"message":"Not found."}}}},"ValidationError":{"description":"Validation error or missing agent_user_id for write actions","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"},"example":{"message":"The body field is required.","errors":{"body":["The body field is required."]}}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"message":"Too Many Attempts."}}}}}},"security":[{"bearerApiKey":[]},{"wiretalkApiKey":[]}]}