REST API

1 min read Updated Mar 11, 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. Find your token in Settings > API Keys in your Social Intents dashboard.

Option 1: Token Header

X-SocialIntentsToken: YOUR_API_TOKEN

Option 2: Basic Auth

Authorization: Basic {base64(accountId:apiToken)}

Base URL

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

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; regenerate it under Settings → API Keys.

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.