# 247Rep Developer API

> 247Rep gives a business a team of AI employees across WhatsApp, Telegram, Email and Voice/SMS. This API gives programmatic access to that assistant: send and receive messages, manage contacts and conversations, run broadcasts, place AI voice calls, and subscribe to real-time events.

- Base URL: `https://api.247rep.app/v1` (also reachable as `https://247rep.app/v1`)
- OpenAPI spec: https://247rep.app/openapi.json
- Human reference: https://247rep.app/api-reference
- Support: support@247rep.app

## Authentication

Bearer token. Generate a key in the dashboard under Developer API.

```
Authorization: Bearer rep_live_xxx
```

- Keys start with `rep_live_` (live) or `rep_test_` (test mode).
- Keys are **channel-scoped**: a WhatsApp key only works on WhatsApp endpoints, a Telegram key only on Telegram endpoints, etc. Using a key on the wrong channel returns `403 FORBIDDEN`.
- `GET /v1/account` returns the identifiers a key belongs to: `id` (stable account/workspace id), `assistantId` (the channel it drives), `keyId`, plus name, email, credit balance and (for WhatsApp) the Meta messaging tier.

## Core concepts

- **Pagination**: list endpoints take `limit` (default 50, max 100) and `cursor`. Responses include `pagination.nextCursor` (null on the last page).
- **Rate limits** (sliding window, per key): sends 100/min (30/min for brand-new keys), broadcasts 10/min, contacts 200/min, reads 300/min, webhooks 20/min. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; a `429` includes `Retry-After` (seconds).
- **Credits**: sends, broadcasts, SMS and email deduct credits from the workspace balance. Text 1, template 3. **Media pricing depends on who hosts the file**: a link you host yourself = flat 1 credit (we don't store it); a URL you got from `POST /v1/media` (we host it) = billed by type — image/photo 2, doc/audio 2, video 5. A `402 INSUFFICIENT_CREDITS` is returned when the balance is too low.
- **Idempotency**: pass an `Idempotency-Key` header on write requests to safely retry without duplicating (Stripe-style).
- **Errors**: JSON `{ "code": "...", "message": "...", "docs": "..." }`. Common codes: `INVALID_KEY`, `FORBIDDEN`, `VALIDATION_ERROR`, `NOT_FOUND`, `INSUFFICIENT_CREDITS`, `RATE_LIMIT_EXCEEDED`.

## Endpoints

### Account
- `GET /v1/account` — who the key belongs to (id, assistantId, keyId, credits, WhatsApp tier).

### Media
- `POST /v1/media` — upload a file (multipart/form-data, field `file`, max 25MB) and get back a hosted `url`. Use it so you never expose your own storage publicly: upload here, then pass the returned `url` as the `link` (WhatsApp) / `url` (Telegram) on a send. Uploading is FREE; the SEND that references a 247Rep-hosted URL is billed by media type. A link you host yourself stays a flat 1 credit (see Credits).

### WhatsApp
- `POST /v1/messages/send` — send text/image/audio/video/document/template/interactive/location. `to` is E.164 (e.g. +2348030000000). Optional `replyTo` (a message id from a webhook or GET /v1/messages, or a raw wamid) threads the send as a quoted reply under that message.
- `POST /v1/messages/{id}/react` — react to a message with an emoji: body `{ "emoji": "👍" }`. Send `{ "emoji": "" }` to remove your reaction. `{id}` is the 247Rep message id. Free (no credits).
- `GET /v1/messages` · `GET /v1/messages/{id}` — read messages.
- `GET /v1/conversations` · `GET /v1/conversations/{id}` · `PATCH /v1/conversations/{id}` · `GET /v1/conversations/{id}/messages` · `POST /v1/conversations/{id}/close`.
- `PATCH /v1/conversations/{id}` — update a conversation. Body `{ "automationEnabled": false }` pauses AI auto-reply on that thread so a human can take over (set `true` to hand it back to the AI) — the same toggle as the dashboard.
- `GET/POST /v1/contacts` · `GET/DELETE /v1/contacts/{id}` — contacts (upsert by phone).
- `POST /v1/broadcast` · `GET /v1/broadcast/{id}` — send to up to 1000 contacts; business-initiated broadcasts usually require an approved template.
- `GET /v1/templates` — approved WhatsApp templates.

### Telegram
- `POST /v1/telegram/send` — send text/photo/video/document/audio. Optional `replyTo` (a 247Rep message id or Telegram's numeric message_id) threads the send as a reply under that message; it is resolved within the target chat because Telegram message ids are only unique per chat.
- `POST /v1/telegram/messages/{id}/react` — react to a message: body `{ "emoji": "👍" }` (empty string removes). `{id}` is the 247Rep message id. Telegram allows only a fixed set of reaction emoji. Free (no credits).
- `GET /v1/telegram/conversations` — conversations, each with `telegramChatId`.

**IMPORTANT — Telegram recipients are numeric chat IDs, not usernames or phone numbers.**
- Send to a numeric `chatId` (e.g. `"123456789"`). You obtain it from an inbound message: the `message.received` webhook, or `GET /v1/telegram/conversations` → `telegramChatId`.
- You can only message a user who has **started your bot first** (Telegram platform rule — bots cannot cold-message people).
- `@channelusername` works only for **public channels your bot administers**, never for individual users.

### Email
- `GET /v1/email/account` · `POST /v1/email/send` · `GET /v1/email/threads` · `GET/PATCH /v1/email/threads/{id}` · `GET /v1/email/contacts` · `GET/POST /v1/email/webhooks` · `DELETE /v1/email/webhooks/{id}`.

### Voice & SMS
- `POST /v1/voip/calls` — start an outbound AI phone call (E.164).
- `POST /v1/voip/sms` — send an SMS.
- `GET /v1/voip/conversations` — voice/SMS conversations.

### Webhooks (real-time events)
- `GET/POST /v1/webhooks` · `DELETE /v1/webhooks/{id}`.
- Events: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`.
- Deliveries are POSTed as JSON and HMAC-SHA256 signed with your subscription secret — verify the signature before trusting a payload.

### No-code triggers (Zapier/Make polling)
- `GET /v1/triggers/new-message` · `new-contact` · `new-order` · `new-appointment` · `campaign-completed` — recent items, newest-first, deduped by `id`.

## Quick start

```bash
# 1. Confirm the key and see who it belongs to
curl https://api.247rep.app/v1/account \
  -H "Authorization: Bearer rep_live_xxx"

# 2. Send a WhatsApp message
curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"+2348030000000","type":"text","text":{"body":"Hello from the API"}}'

# 3. Receive messages — subscribe a webhook
curl -X POST https://api.247rep.app/v1/webhooks \
  -H "Authorization: Bearer rep_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/247rep","events":["message.received"],"secret":"whsec_your_secret"}'
```