Skip to main content

​
CriaChat Developer Guide

This guide is for builders implementing CriaChat in real environments: automations, CRM sync, scheduling flows, internal tooling, and quality controls. CriaChat integrations usually work best with a simple architecture:
  • Events (webhooks) to detect what happened
  • Commands (Application API calls) to act on it
  • Client APIs when you embed a custom chat experience for end-users

​
Integration surfaces

​
1) Application APIs (operator-grade)

Use when your integration behaves like an internal operator:
  • manage contacts, inboxes, agents
  • read and update conversations
  • post messages and internal notes
  • apply tags/labels and routing logic
  • configure automation rules where available
Authentication is done with api_access_token in request headers.

​
2) Webhooks (event-driven automations)

Use webhooks to trigger workflows when something changes:
  • new message received
  • conversation status updated
  • assignment changed
  • tags applied, etc.
Then run your business logic outside CriaChat (CRM updates, alerts, scheduling, enrichment).

​
3) Client APIs (end-user interfaces)

Use when your integration behaves like an end-user UI:
  • embed chat in a web app or mobile app
  • build a custom widget or opinionated interface
  • control contact identity and conversation creation
Client APIs use identifiers such as inbox_identifier and contact_identifier.
  1. Start with a stable inbox
    • connect the channel
    • validate message flow end-to-end
    • define tagging and assignment rules
  2. Add observability
    • log key identifiers (account, inbox, conversation, message)
    • store webhook payloads for debugging (with retention limits)
  3. Automate with idempotency
    • treat webhooks as “may repeat”
    • design handlers safe to retry
    • use backoff for transient failures
  4. Scale with clear boundaries
    • keep business logic in your automation layer (e.g., n8n)
    • keep CriaChat as the system of record for messaging state

​
Security fundamentals

  • Treat api_access_token as a secret (store in a secrets manager)
  • Rotate tokens according to your internal policy
  • Restrict token distribution to only the services that need it
  • Avoid exposing Application API tokens in client-side code

​
Quick example (Application API)

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