Skip to main content

​
Introduction to CriaChat APIs

Welcome to the CriaChat API Reference. This section explains how the APIs are organized, how authentication works, and how to make your first requests. CriaChat provides public API categories designed for different integration needs:
  • Application APIs — workspace automation and agent-facing integrations.
  • Client APIs — custom chat interfaces and end-user messaging experiences.
  • Other APIs — feature-specific endpoints used in certain flows (documented in their sections).

​
Base URL

All API requests use: https://app.cria.chat/

​
Authentication

​
Application APIs

Application APIs authenticate via a request header:
  • api_access_token: <YOUR_API_ACCESS_TOKEN>
Keep this token server-side. Treat it as a secret.

​
Client APIs

Client APIs are designed for end-user chat surfaces and typically use identifiers instead of an API token:
  • inbox_identifier
  • contact_identifier
contact_identifier is the source id returned when creating a contact (source_id). Some Client API payloads also support an identifier_hash field for HMAC-style verification, depending on your use case.

​
API namespaces (by path)

CriaChat separates intent by URL prefix:
  • Application APIs: /api/v1/...
  • Client APIs: /public/api/v1/...
  • Other APIs: documented in their respective sections

​
Quickstart (Application API)

​
Verify your token

curl -X GET "https://app.cria.chat/api/v1/profile" \
  -H "api_access_token: YOUR_API_ACCESS_TOKEN"

​
Quickstart (Client API)

This is the common “happy path” for embedded chat experiences: create contact → create conversation → send message.

​
1) Create (or update) a contact

curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "external-user-123",
    "name": "Alice",
    "email": "alice@acme.inc",
    "phone_number": "+5511999999999",
    "custom_attributes": {}
  }'
From the response, store:
  • source_id → this is your contact_identifier

​
2) Create a conversation

curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/CONTACT_IDENTIFIER/conversations" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_attributes": {}
  }'
From the response, store:
  • id → this is your conversation_id

​
3) Send a message

curl -X POST "https://app.cria.chat/public/api/v1/inboxes/INBOX_IDENTIFIER/contacts/CONTACT_IDENTIFIER/conversations/CONVERSATION_ID/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! I need help with my order."
  }'

​
Conventions and reliability notes

  • Use the correct namespace: /api/v1 (Application) vs /public/api/v1 (Client)
  • Treat webhook/event deliveries (when enabled) as “may repeat” signals and implement idempotency in your automation layer
  • Log key identifiers for debugging: inbox_identifier, contact_identifier, conversation_id, message_id

​
Troubleshooting

When behavior differs from expectations:
  • Confirm the base URL and path prefix (/api/v1 vs /public/api/v1)
  • Confirm whether the endpoint expects api_access_token or identifiers
  • Inspect real requests made by the CriaChat UI (browser DevTools → Network) and replicate the same payload structure