> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cria.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Guide

> Integration patterns, automation architecture, and reliable operations on top of CriaChat.

# 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`.

## Recommended implementation workflow

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)

```bash theme={null}
curl -X GET "https://app.cria.chat/api/v1/profile" \
  -H "api_access_token: YOUR_API_ACCESS_TOKEN"
```