REST API overview

Base URL: https://api.byotalk.com/v1. JSON over HTTPS. Every response carries a Request-Id header; include it when you contact support.

Conventions

Authentication

The environment is derived from the credential. Client endpoints may name the environment with ?env= or the Byotalk-Env header (required for dev tokens); it must match the environment of the key that signed the token.

Versioning

• Major version in the path (/v1). Only additive changes within v1 (new endpoints, new optional fields, new enum values clients must tolerate, new event types).
• Breaking changes → /v2 with ≥ 12 months of overlap and deprecation headers (Deprecation, Sunset).

Identifiers and formats

• User IDs are the customer's strings: 1–128 chars of [A-Za-z0-9_\-@.:].
• JSON bodies use camelCase. Timestamps ISO 8601 UTC (2026-10-04T10:00:00.123Z).
• Unknown request fields → 400 unknown_field (strict). Responses may gain fields; clients must ignore unknown ones.

Pagination

GET /v1/conversations?limit=20&cursor=eyJ0IjoiMjAyNi0x...

{ "data": [ ... ], "nextCursor": "eyJ0IjoiMjAyNi0x..." }

• limit default 50, max 200. nextCursor is opaque; null at the end.
• Messages and events also accept before / after (seq) because seq is meaningful.

Idempotency

• Idempotency-Key: <uuid> accepted on every POST, PATCH, DELETE; kept 24 h per (environment, key, route).
• Replay with same body → stored status + body, header Idempotent-Replayed: true.
• Same key, different body → 422 idempotency_mismatch.
• Message sends also accept clientMsgId in the body (shared dedup with the socket path, 48 h).

Request IDs

Every response includes Request-Id: req_.... It appears in error bodies, dashboard logs and webhook delivery logs.

Errors

{
  "error": {
    "type": "invalid_request",
    "code": "text_too_long",
    "message": "text must be at most 5000 characters",
    "param": "text",
    "requestId": "req_01J9ZK..."
  }
}

This is the single error catalogue for REST and the realtime socket. Socket errors arrive as {"t":"error","re":...,"code":...} frames or as close codes (see Realtime protocol).

Every error body carries requestId; retryable errors carry retryAfterMs.

Rate limits

Headers on every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. 429 adds Retry-After (seconds).

Paid plans raise the secret-key limit.

Limits

Resources

Tokens

POST /v1/tokens — server. Mint a user token for backends without our SDK (the Node SDK signs locally instead).

// request
{ "userId": "user_123", "expiresIn": 3600 }
// response 201
{ "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6ImtleV8wMUo5In0...", "expiresAt": "2026-10-04T11:00:00Z" }

Users

// PUT /v1/users/user_123
{ "name": "Asha Rao", "imageUrl": "https://cdn.example.com/a.png", "metadata": { "plan": "pro" } }
// 200
{ "id": "user_123", "name": "Asha Rao", "imageUrl": "https://cdn.example.com/a.png",
  "metadata": { "plan": "pro" }, "createdAt": "2026-10-04T09:00:00Z" }

Conversations

// POST /v1/conversations  (direct; idempotent by pair)
{ "type": "direct", "members": ["user_123", "user_456"] }
// POST /v1/conversations  (group)
{ "type": "group", "name": "Order #8812", "members": ["user_123", "user_456", "user_789"],
  "metadata": { "orderId": "8812" } }
// 201
{ "id": "conv_01J9ZK...", "type": "group", "name": "Order #8812", "metadata": { "orderId": "8812" },
  "lastSeq": 3, "createdAt": "2026-10-04T10:00:00Z",
  "members": [ { "userId": "user_123", "role": "owner" }, { "userId": "user_456", "role": "member" },
               { "userId": "user_789", "role": "member" } ] }

Client creating a group becomes owner. A server-created group sets ownerId explicitly or has no owner (server-only management). New members see full history in Phase 1.

// GET /v1/conversations?limit=2  (client)
{ "data": [
    { "id": "conv_01J9ZK...", "type": "group", "name": "Order #8812", "lastSeq": 812,
      "unreadCount": 3, "lastReadSeq": 809, "muted": false,
      "lastMessage": { "id": "msg_01J9...", "seq": 812, "senderId": "user_456", "text": "Shipped!",
                       "createdAt": "2026-10-04T10:05:00Z" } }
  ],
  "nextCursor": "eyJ..." }

Members

Messages

// POST /v1/conversations/conv_01J9ZK.../messages
{ "clientMsgId": "0192f0c4-7b1e-7c3a-9a55-3f1d2c0e9b11",
  "text": "Can you share the invoice?",
  "replyTo": "msg_01J9ZJ...",
  "attachments": ["att_01J9ZM..."],
  "metadata": { "intent": "invoice_request" } }
// 201
{ "id": "msg_01J9ZN...", "conversationId": "conv_01J9ZK...", "seq": 813, "senderId": "user_123",
  "text": "Can you share the invoice?", "replyTo": "msg_01J9ZJ...",
  "attachments": [ { "id": "att_01J9ZM...", "name": "photo.jpg", "size": 482113,
                     "mimeType": "image/jpeg", "width": 1200, "height": 900 } ],
  "metadata": { "intent": "invoice_request" }, "version": 1,
  "createdAt": "2026-10-04T10:06:00.120Z", "editedAt": null, "deletedAt": null }

// GET /v1/conversations/conv_01J9ZK.../messages?before=813&limit=50
{ "data": [ { "id": "msg_...", "seq": 812, ... }, ... ],   // descending seq
  "hasMore": true }
// 503 when part of the page lives in an unavailable customer DB
{ "error": { "type": "unavailable", "code": "history_unavailable",
             "message": "Older history is temporarily unavailable", "retryAfterMs": 30000,
             "requestId": "req_..." } }

Deleted messages are returned as tombstones: { id, seq, senderId, deletedAt, text: null, attachments: [] }.

Sync and events

// POST /v1/sync
{ "cursor": "c_1791100000000" }
// 200
{ "conversations": [ { "id": "conv_01J9ZK...", "lastSeq": 815, "unreadCount": 2 } ],
  "removed": [ "conv_01J8AA..." ],
  "cursor": "c_1791100420000",
  "fullReload": false }

// GET /v1/conversations/conv_01J9ZK.../events?after=812
{ "data": [
    { "seq": 813, "type": "message.new", "message": { ... } },
    { "seq": 814, "type": "message.updated", "message": { "id": "msg_...", "version": 2, ... } },
    { "seq": 815, "type": "member.added", "userId": "user_999", "actorId": "user_123" } ],
  "hasMore": false }
// 410 when after < buffer floor or gap > 1000
{ "error": { "type": "conflict", "code": "resync_required", ... } }

Read state

POST /v1/conversations/{id}/read — client. { "seq": 815 }. Monotonic (lower values ignored). Emits receipt to members and coalesced message.read webhook.

Uploads and attachments

Files go straight from the client to the environment's media storage (your own Cloudinary, S3-compatible bucket or Azure Blob container when connected, otherwise ours) and never transit our servers. See Media storage.

// POST /v1/uploads
{ "conversationId": "conv_01J9ZK...", "filename": "photo.jpg", "size": 482113,
  "contentType": "image/jpeg", "width": 1200, "height": 900 }
// 201
{ "attachmentId": "att_01J9ZM...",
  "upload": { "method": "POST", "url": "https://api.cloudinary.com/v1_1/<cloud>/image/upload",
              "fields": { "public_id": "byotalk/env_.../conv_01J9ZK.../att_01J9ZM...", "timestamp": "1791100000",
                          "type": "authenticated", "api_key": "...", "signature": "..." } },
  "expiresAt": "2026-10-04T10:16:00Z" }
// client: multipart POST to upload.url with every field plus "file"
// POST /v1/uploads/att_01J9ZM.../complete
{ "id": "att_01J9ZM...", "name": "photo.jpg", "size": 482113, "mimeType": "image/jpeg",
  "width": 1200, "height": 900, "status": "ready" }
// GET /v1/attachments/att_01J9ZM.../url
{ "url": "https://api.cloudinary.com/v1_1/<cloud>/image/download?public_id=...&expires_at=...&signature=...",
  "expiresAt": "2026-10-04T10:11:00Z" }

For Cloudinary, the upload url path segment is image, video (also used for audio) or raw (documents and other files). Errors: 413 file_too_large, 400 invalid_request (type not allowed, or not a valid image/video), 422 attachment_not_ready (complete called before the upload finished), 503 storage_unavailable (no media storage configured or the provider is unreachable).

Push devices

Webhooks

// POST /v1/webhooks
{ "url": "https://api.example.com/chat-webhooks",
  "events": ["message.created", "message.deleted", "member.added", "sink.failing"] }
// 201 (secret shown once)
{ "id": "wh_01J9...", "url": "...", "events": [...], "status": "enabled", "secret": "whsec_MfKQ9r8G..." }

Storage (dashboard session)

Session cookie plus Byotalk-Env; changes need a sign-in within 15 minutes (403 reauth_required) and are audited.

Calls

POST /v1/calls, GET /v1/calls, GET /v1/calls/{id}, POST /v1/calls/{id}/join|decline|leave (client), and POST /v1/calls/{id}/end, .../participants/{userId}/remove|mute (server, dashboard). Request bodies, the call object and errors: Voice and video calls.

Analytics

GET /v1/analytics?from=2026-10-01&to=2026-10-04&granularity=day — server key or dashboard. granularity=hour covers at most 7 days, day at most 366. Add format=csv for the time series as CSV. Counts only; no message text is read. Totals include calls, videoCalls, callsAnswered, callsMissed, callAnswerRate, callMinutes (participant minutes) and avgCallSeconds; series rows include calls, callsAnswered, callsMissed and callMinutes.

{ "range": { "from": "...", "to": "...", "granularity": "day", "timezone": "UTC" },
  "totals": { "messages": 1520, "activeUsers": 64, "newUsers": 12, "conversations": 30, "messagesPerActiveUser": 23.8,
              "mauThisMonth": 80, "peakConnections": 21, "webhookSuccessRate": 0.998, "avgAckMs": 14, "avgFanoutMs": 9, "...": "..." },
  "series": [ { "t": "2026-10-01T00:00:00.000Z", "messages": 410, "activeUsers": 30, "...": "..." } ],
  "topConversations": [ { "id": "conv_...", "name": "Order #8812", "type": "group", "messages": 120, "senders": 3, "lastAt": "..." } ],
  "topSenders": [ { "userId": "user_123", "name": "Asha", "messages": 210 } ],
  "heatmap": [[0, 0, "... 24 values per weekday, Monday first, UTC hours"]],
  "live": { "connections": 12 },
  "plan": { "name": "starter", "mauLimit": 2500, "connectionLimit": 250 },
  "storage": { "mode": "byo_db", "sink": { "status": "healthy", "lagSeconds": 2 } } }

Usage

GET /v1/usage?from=2026-10-01&to=2026-10-04&granularity=day — server, dashboard.

{ "data": [ { "date": "2026-10-01", "mau": 812, "peakConnections": 63, "messages": 14092,
              "apiRequests": 30111, "webhookDeliveries": 14800, "pushSent": 2203 } ],
  "plan": { "name": "starter", "mauLimit": 2500, "connectionLimit": 250 } }

Health

The gateway exposes the same two paths on rt.byotalk.com.

Server SDK mapping

Webhook events and signature verification: see Webhooks.