REST API

2 min read Updated Nov 3, 2026 Integrations

The Social Intents REST API lets you access chat data, contacts, offline messages, and widget information programmatically.

Authentication

All API requests require authentication using your API token. Admins find it under Settings > API & Webhooks > REST API, which shows your Account ID (username) and API token (password). The REST API card on the Integrations page links there too (View API key). Keep the token secret: anyone with it can read your chat data.

Option 1: Token Header

X-SocialIntentsToken: YOUR_API_TOKEN

Option 2: Basic Auth (shown in Settings)

Authorization: Basic {base64(accountId:apiToken)}

Base URL

https://api.socialintents.com/v1/api

This is the base URL shown under Settings > API & Webhooks, along with a ready-to-copy curl example that uses your own credentials. Requests to https://www.socialintents.com/v1/api also work.

Endpoints

Health Check

GET /api/ping

Returns {"statusCode":"200","status":"PingSuccessful"}

Get Chats

GET /api/chats

Returns answered and missed chats. Supports filtering:

Parameter	Description
`date_from`	Start date (e.g., 2025-01-01)
`date_to`	End date
`timezone`	Timezone for date filtering
`app_id` or `widget_id`	Filter by widget
`tag`	Filter by tag
`visitor_id`	Filter by visitor
`email`	Filter by visitor email
`id`	Get a specific chat by ID

Get Offline Messages

GET /api/offlinemessages

Returns offline messages with the same filter parameters as chats.

Get Missed Chats

GET /api/missedchats

Returns missed chats only, with the same filter parameters.

Get Contacts / Leads

GET /api/contacts

Returns captured leads. Supports date_from, date_to, timezone, and app_id filters.

Get Widgets

GET /api/apps

Returns a list of your widgets with ID, name, timezone, and creation date.

Webhook Management

POST /api/apps/{appId}/webhook
DELETE /api/apps/{appId}/webhook/{webhookId}
DELETE /api/webhook/{webhookId}

See Webhooks for details.

Chat Response Format

Each chat object includes:

id, chatType (Answered/Missed/Offline Message), appId
visitorFullName, visitorEmail, visitorPhone
agentName, agentId, agentEmail
duration, startDate, visits
page, referrer, ip, location, userAgent
visitorCustom1 through visitorCustom6, visitorParams
textBody (plain text transcript), htmlBody (HTML transcript)
messages[] - array of individual messages with body, nickname, timestamp, type

Rate Limits

API requests are subject to reasonable rate limits. If you receive a 429 response, reduce your request frequency.

Example Request

curl -H "X-SocialIntentsToken: YOUR_API_TOKEN" \
  "https://www.socialintents.com/v1/api/chats?date_from=2026-01-01&date_to=2026-01-31&timezone=America/New_York"

Responses are JSON. A 401 response means the token is missing or invalid; check the credentials under Settings > API & Webhooks.

Common Integration Patterns

Nightly warehouse export - Pull /api/chats with yesterday's date_from/date_to on a schedule and load into your data warehouse.
CRM sync - Poll /api/contacts for new leads, or skip polling entirely and use push-based webhooks.
Missed-chat follow-up - Fetch /api/missedchats each morning and feed your follow-up queue with visitor emails and the pages they were on.
Per-visitor history - Query /api/chats?email=... to show a visitor's chat history inside your own support tooling.