Support API Reference

Complete reference for all Support API endpoints.

Authentication

All API requests require an API key:

curl -X GET https://api.usetransactional.com/support/conversations \
  -H "X-API-Key: your-api-key"

Base URL

https://api.usetransactional.com/support

Conversations

List Conversations

GET /conversations

Query parameters:

Parameter	Type	Description
`status`	string	`open`, `pending`, `resolved`, `closed`
`inboxId`	string	Filter by inbox
`assigneeId`	string	Filter by assignee
`visitorId`	string	Filter by visitor
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

Get Conversation

GET /conversations/:conversationId

Reply to Conversation

POST /conversations/:conversationId/reply

Request body:

{
  "message": "Thanks for reaching out!",
  "type": "reply"
}

Field	Type	Required	Description
`message`	string	Yes	Message content
`type`	string	No	`reply` (default) or `note`
`attachments`	array	No	File attachments

Assign Conversation

POST /conversations/:conversationId/assign

Request body:

{
  "assigneeId": "user-123"
}

Update Conversation Status

PUT /conversations/:conversationId

Request body:

{
  "status": "resolved"
}

Snooze Conversation

POST /conversations/:conversationId/snooze

Request body:

{
  "until": "2024-01-16T09:00:00Z"
}

Add Tags

POST /conversations/:conversationId/tags

Request body:

{
  "tags": ["billing", "urgent"]
}

Remove Tag

DELETE /conversations/:conversationId/tags/:tagId

Visitors

List Visitors

GET /visitors

Query parameters:

Parameter	Type	Description
`search`	string	Search by name or email
`identified`	boolean	Filter by identification status
`companyId`	string	Filter by company
`page`	number	Page number
`limit`	number	Items per page

Get Visitor

GET /visitors/:visitorId

Update Visitor

PUT /visitors/:visitorId

Request body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "attributes": {
    "plan": "enterprise"
  }
}

Delete Visitor

DELETE /visitors/:visitorId

Get Visitor Sessions

GET /visitors/:visitorId/sessions

Get Visitor Events

GET /visitors/:visitorId/events

Get Visitor Conversations

GET /visitors/:visitorId/conversations

Associate Visitor with Company

PUT /visitors/:visitorId/company

Request body:

{
  "companyId": "company-123"
}

Export Visitor Data

GET /visitors/:visitorId/export

Anonymize Visitor

POST /visitors/:visitorId/anonymize

Companies

List Companies

GET /companies

Query parameters:

Parameter	Type	Description
`search`	string	Search by name
`industry`	string	Filter by industry
`page`	number	Page number
`limit`	number	Items per page

Get Company

GET /companies/:companyId

Create Company

POST /companies

Request body:

{
  "id": "company-123",
  "name": "Acme Inc",
  "website": "https://acme.com",
  "attributes": {
    "plan": "enterprise",
    "industry": "Technology"
  }
}

Update Company

PUT /companies/:companyId

Delete Company

DELETE /companies/:companyId

Get Company Users

GET /companies/:companyId/users

Get Company Conversations

GET /companies/:companyId/conversations

Get Company Stats

GET /companies/:companyId/stats

Add Company Note

POST /companies/:companyId/notes

Request body:

{
  "content": "Enterprise renewal coming up in Q1"
}

Inboxes

List Inboxes

GET /inboxes

Get Inbox

GET /inboxes/:inboxId

Create Inbox

POST /inboxes

Request body:

{
  "name": "Technical Support",
  "description": "Technical issues and questions",
  "email": "support@example.com"
}

Update Inbox

PUT /inboxes/:inboxId

Delete Inbox

DELETE /inboxes/:inboxId

Get Inbox Stats

GET /inboxes/:inboxId/stats

List Inbox Members

GET /inboxes/:inboxId/members

Add Inbox Member

POST /inboxes/:inboxId/members

Request body:

{
  "userId": "user-123",
  "role": "agent"
}

Remove Inbox Member

DELETE /inboxes/:inboxId/members/:userId

Update Member Availability

PUT /inboxes/:inboxId/members/:userId/availability

Request body:

{
  "status": "available"
}

Canned Responses

List Canned Responses

GET /canned-responses

Get Canned Response

GET /canned-responses/:responseId

Create Canned Response

POST /canned-responses

Request body:

{
  "title": "Greeting",
  "shortcut": "/hello",
  "content": "Hi {{visitor.name}}! How can I help?"
}

Update Canned Response

PUT /canned-responses/:responseId

Delete Canned Response

DELETE /canned-responses/:responseId

Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request body:

{
  "url": "https://your-server.com/webhook",
  "events": ["conversation.created", "message.received"],
  "secret": "your-webhook-secret"
}

Delete Webhook

DELETE /webhooks/:webhookId

Get Webhook Logs

GET /webhooks/:webhookId/logs

Analytics

Get Overview Stats

GET /analytics/overview

Query parameters:

Parameter	Type	Description
`startDate`	string	Start date (ISO 8601)
`endDate`	string	End date (ISO 8601)

Get Conversation Analytics

GET /analytics/conversations

Get Team Performance

GET /analytics/team

Get Response Time Analytics

GET /analytics/response-time

Error Responses

All endpoints return errors in this format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Conversation not found"
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Access denied
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

Endpoint Type	Rate Limit
Standard APIs	100 req/min
Webhooks	1000 req/min

Webhook Events

Event	Description
`conversation.created`	New conversation started
`conversation.assigned`	Conversation assigned to agent
`conversation.resolved`	Conversation marked resolved
`conversation.closed`	Conversation closed
`message.received`	New message from visitor
`message.sent`	Agent sent a message
`visitor.identified`	Visitor was identified
`visitor.updated`	Visitor attributes updated

Next Steps

Chat Widget - Widget SDK documentation
Inboxes - Managing inboxes
Conversations - Handling conversations