Connecting live chat

Sonar doesn't run a chat widget. Instead, your chat platform sends each conversation to Sonar, and we match it to the visitor who had it. In Live chat and Sessions you then see who chatted, which pages they viewed, and whether they converted.

The webhook

Send a POST request with a JSON body to:

https://sonar-app.co.uk/api/chat/webhook

You'll find the exact address, with an example for your site, under Live chat → Connect your chat platform.

A conversation with its messages:

{
  "website_url": "https://example.com",
  "conversation_id": "abc123",
  "ip": "203.0.113.10",
  "browser": "Chrome",
  "device_type": "desktop",
  "messages": [
    { "role": "visitor", "content": "Hi, do you ship to Ireland?", "created_at": "2026-10-07T10:15:00Z" },
    { "role": "agent", "content": "We do, usually in 2 days.", "created_at": "2026-10-07T10:16:10Z" }
  ]
}

Or one message per request, as most chat platforms send them:

{
  "website_url": "https://example.com",
  "conversation_id": "abc123",
  "role": "visitor",
  "content": "Hi, do you ship to Ireland?",
  "created_at": "2026-10-07T10:15:00Z",
  "ip": "203.0.113.10"
}

You can also send an array of either.

Field	Required	Notes
website_url	Yes	The site the chat happened on. Matched to your Sonar site by domain.
conversation_id	Yes	Your chat platform's ID for the conversation. Messages with the same ID are grouped.
role	Yes	visitor or agent.
content	Yes	The message text.
created_at	Yes	When the message was sent, as an ISO 8601 date and time.
ip	Recommended	The visitor's IP address. This is how the chat is matched to their visit.
user_agent, browser, os, device_type	No	The visitor's browser details.
country, city	No	The visitor's location.
page_url	No	The page the chat started on.
visitor_name, visitor_email	No	If the visitor gave them.
site_key	No	Your site's Site Key. Only needed if more than one Sonar site uses the same domain.

Sending the same message again is safe: duplicates are ignored. Visitor details fill in what's missing and never erase what's already known.

The response tells you which site the conversation was saved to and whether the visitor was matched to a visit:

{
  "ok": true,
  "conversations": [{
    "site_id": 1,
    "conversation_id": "abc123",
    "messages_added": 2,
    "duplicates_ignored": 0,
    "visitor": { "matched": true, "session_id": "…" }
  }]
}

Matching chats to visitors

A chat is matched to a visit when the visitor's IP viewed pages on the site within 30 minutes of the chat, the same rule Sessions uses. Without an ip, the conversation is still saved and shown in Live chat, but it isn't linked to a visit.

Unread conversations

A conversation is unread when the visitor has written since you last opened it; agent replies don't count. Unread conversations are highlighted in Live chat and counted on the sidebar badge. Opening one marks it read, and you can use Mark as unread to come back to it, or Mark all as read to clear the list. Read state is per person, so each teammate sees their own.