# Tarangai

> Tarangai is a WhatsApp-first business communication platform. Connect a WhatsApp Business number, then use the API to send messages, manage contacts, run campaigns, and deploy AI agents — all scoped to your workspace.

## Docs

- [API Reference](https://tarangai.co/docs): Full endpoint reference for external integrations
- [Developer Settings](https://tarangai.co/dashboard/settings/developer): API key generation and webhook URLs (requires login)

## Authentication

All API requests go to `https://tarangai.co/api/v1/`. Authenticate with an API key:

```
X-API-Key: jlb_<prefix>_<secret>
```

API keys are generated from the developer settings page after signing up. Each key is scoped to one workspace (tenant).

## Core concepts

- **Tenant** — your workspace. Every API key, channel, contact, and conversation belongs to one tenant.
- **Channel** — a connected WhatsApp (or Instagram/Facebook) number. One tenant can have multiple channels.
- **Contact** — a person identified by phone number. Contacts belong to one tenant.
- **Conversation** — a messaging thread between your workspace and a contact on a channel.
- **Agent** — an AI agent that can auto-reply in conversations using a configurable system prompt and knowledge base.
- **Campaign** — a bulk message send to a segment of contacts using a WhatsApp template.
- **Template** — a Meta-approved WhatsApp message template used for outbound messaging.

## Key endpoints

### Workspace
- `GET /api/v1/tenants/me` — current workspace info
- `GET /api/v1/channels` — list connected channels

### Contacts
- `GET /api/v1/contacts` — list contacts (filter by tag, segment, search query)
- `POST /api/v1/contacts` — create a contact
- `PATCH /api/v1/contacts/:id` — update contact
- `DELETE /api/v1/contacts/:id` — permanently delete a contact (dashboard owner/admin only)
- `POST /api/v1/contacts/:id/opt-out` — opt contact out of messaging
- `POST /api/v1/contacts/:id/conversations` — start a conversation

### Conversations & messaging
- `GET /api/v1/conversations` — list conversations (filter by status, channel, assignee)
- `GET /api/v1/conversations/:id/messages` — get messages in a conversation
- `POST /api/v1/conversations/:id/messages` — send a message
- `PATCH /api/v1/conversations/:id/status` — update status (open, resolved, pending)
- `PATCH /api/v1/conversations/:id/assign` — assign to a team member

### Templates
- `GET /api/v1/templates` — list templates
- `POST /api/v1/templates/:id/send` — send a template to a contact
- `POST /api/v1/templates/:id/submit` — submit for Meta approval

### Campaigns
- `POST /api/v1/campaigns` — create a campaign
- `POST /api/v1/campaigns/:id/execute` — send immediately
- `GET /api/v1/campaigns/:id/insights` — delivery and engagement stats

### AI agents
- `GET /api/v1/agents` — list agents
- `POST /api/v1/agents` — create an agent
- `POST /api/v1/agents/:id/test` — test an agent with a sample message

### Analytics
- `GET /api/v1/analytics/overview` — message volume, delivery rates, open rates
- `GET /api/v1/analytics/usage` — usage against plan limits

## Webhooks

Each workspace has tenant-scoped webhook URLs. Find yours in the developer settings page.

- WhatsApp: `https://tarangai.co/webhook/:slug/whatsapp`
- Instagram: `https://tarangai.co/webhook/:slug/instagram`
- Shopify: `https://tarangai.co/webhook/:slug/shopify`

## Quick start

```bash
# 1. Verify your API key
curl https://tarangai.co/api/v1/tenants/me \
  -H "X-API-Key: jlb_xxxx_..."

# 2. List your contacts
curl https://tarangai.co/api/v1/contacts \
  -H "X-API-Key: jlb_xxxx_..."

# 3. Send a message
curl -X POST https://tarangai.co/api/v1/conversations/CONV_ID/messages \
  -H "X-API-Key: jlb_xxxx_..." \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello from the API"}'
```