Name: 247Rep
Price: 1000 NGN
Availability: InStock
Rating: 4.8 (500 reviews)
Author: 247Rep

Overview

The 247Rep API lets you integrate WhatsApp and email messaging directly into your own products and workflows. It is organised around REST: resources are accessed at predictable URLs, requests use standard HTTP verbs, and every response is JSON.

All requests must be made over HTTPS and authenticated with an API key.

JSON request and response bodies
Bearer token authentication with scoped, revocable API keys
Separate test and live environments
Cursor-based pagination on all list endpoints
Per-endpoint rate limiting with standard X-RateLimit-* headers
Real-time webhooks for inbound and delivery events

Base URL

All API endpoints are relative to the following base URL:

text

https://api.247rep.app/v1

For example, to send a WhatsApp message you would issue a POST request to https://api.247rep.app/v1/messages/send.

Test & live modes

Every workspace has two independent API environments, identified by the key prefix. The environment is inferred from the key you authenticate with — there is no separate header.

Prefix	Mode	Behaviour
`rep_live_…`	Live	Sends real messages and deducts real credits.
`rep_test_…`	Test	Validates and authenticates exactly like live, but never sends a real message and never deducts credits. Mutating endpoints return a mock response with test: true.

Use a test key in development and CI. Test-mode send and broadcast calls return a synthetic messageId/broadcastId and creditsUsed: 0.

API keys

Authenticate every request with a secret API key. Create and revoke keys in your dashboard under Developer API. Each key is scoped to a single workspace and channel, and can be generated for either the test or live environment.

Your secret keys carry many privileges — keep them secure. Never expose a key in client-side code, public repositories, or anywhere a customer could read it. If a key leaks, revoke it immediately from the dashboard.

Keys are shown in full only once at creation. 247Rep stores only a SHA-256 hash, so a lost key cannot be recovered — generate a new one instead.

Authorization header

Pass your key as a bearer token in the Authorization header on every request:

http

Authorization: Bearer rep_live_your_key_here

A request with a missing, malformed, or revoked key returns 401 Unauthorized:

json

{
  "code": "INVALID_KEY",
  "message": "Invalid API key"
}

Quick start

Send your first WhatsApp message in one request. Replace the key and recipient with your own.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": { "body": "Hello from 247Rep!" }
  }'

typescript

const res = await fetch("https://api.247rep.app/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer rep_live_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+2348012345678",
    type: "text",
    text: { body: "Hello from 247Rep!" },
  }),
});
const data = await res.json();

python

import requests

res = requests.post(
    "https://api.247rep.app/v1/messages/send",
    headers={"Authorization": "Bearer rep_live_your_key"},
    json={
        "to": "+2348012345678",
        "type": "text",
        "text": {"body": "Hello from 247Rep!"},
    },
)
data = res.json()

Pagination

List endpoints are cursor-paginated. Pass limit (default 50, max 100) and a cursor to fetch the next page. Each response includes hasMore and a nextCursor — pass that value as the cursor on the following request.

Parameters

limit

integeroptional

Items per page. Default 50, maximum 100.

cursor

stringoptional

The nextCursor returned by the previous page.

json

{
  "data": [ /* ... items ... */ ],
  "hasMore": true,
  "nextCursor": "cm5a1b2c3d4e5f6g7h8i9j0k"
}

Rate limits

Rate limits are applied per API key and vary by endpoint category. A global burst limit of 20 requests/second also applies across all endpoints.

Category	Limit	Applies to
Send	100 / min	Sending messages, closing conversations, deleting contacts
Broadcast	10 / min	Broadcast sends
Contacts (write)	200 / min	Creating / upserting contacts
Read	300 / min	All GET endpoints
Webhooks	20 / min	Creating / deleting webhooks
Burst	20 / sec	All endpoints (global)

New API keys are limited to 30 send/min and 5 broadcast/min for their first 7 days. These tighten abuse risk on fresh keys and lift automatically afterward.

Every response includes the current limit state:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1718745600

When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header (seconds):

json

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please retry after the specified time."
}

Idempotency

Network errors happen. If your server retries a send and we already processed the first attempt, you do not want a second message going out. Every write endpoint (anything that sends a message, broadcasts, closes a conversation, creates or deletes a webhook, etc.) accepts an Idempotency-Key header. Set it to a unique value per logical request (a UUID works well) and we will return the original response on any retry within 24 hours.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Idempotency-Key: 8c3d2f60-4e6e-4b4e-9a5d-1d92f1d8d8a1" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": { "body": "Hello" }
  }'

How it behaves

First request with a given key runs normally and we cache the response for 24 hours.
Any retry within 24 hours that reuses the same key replays the original response with header Idempotent-Replayed: true. No duplicate send, no duplicate credit charge.
If a retry sends a different body with the same key, we return 409 Conflict with code IDEMPOTENCY_CONFLICT. Use a fresh key for a different payload.
If two requests with the same key arrive at the same time, the second one gets 409 with code IDEMPOTENCY_IN_PROGRESS. Wait a moment and retry.

Always generate the key on YOUR server, not the client. That way a flaky browser retry never starts a second message.

Credits & costs

Sending messages consumes credits from your workspace balance. The cost depends on the channel and the message type. Read endpoints are free. Inbound messages are free.

Channel	Action	Cost
WhatsApp / Telegram	Text message	1 credit
WhatsApp / Telegram	Image	2 credits
WhatsApp / Telegram	Video	5 credits
WhatsApp / Telegram	Document or audio	2 credits
WhatsApp	Template message	2 credits
Email	Any email (with or without attachments)	1 credit
WhatsApp	Broadcast	Per recipient (same as the underlying message type)

Send responses include creditsUsed and the remaining creditsRemaining balance. If your balance is too low the API returns 402 Payment Required with code INSUFFICIENT_CREDITS. In test mode creditsUsed is always 0.

Errors

247Rep uses conventional HTTP status codes. 2xx indicates success, 4xx a problem with the request, and 5xx a server error. Every error body has the same shape:

json

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. Required: 2, available: 0",
  "docs": "https://docs.247rep.com/errors#INSUFFICIENT_CREDITS"
}

Code	HTTP	Meaning
`INVALID_AUTH`	401	Missing or malformed Authorization header.
`INVALID_KEY`	401	The API key does not exist or has the wrong format.
`REVOKED_KEY`	401	The API key has been revoked.
`FORBIDDEN`	403	Key not authorized for this resource (e.g. email endpoints require an email channel key).
`INSUFFICIENT_CREDITS`	402	Workspace balance is too low for this action.
`VALIDATION_ERROR`	400	The request body failed validation.
`NOT_CONFIGURED`	400	WhatsApp is not configured for this channel.
`NO_RECIPIENTS`	400	No valid recipients were found for a broadcast.
`WEBHOOK_VERIFICATION_FAILED`	400	Your endpoint did not echo the verification challenge.
`NOT_FOUND`	404	The requested resource does not exist.
`RATE_LIMIT_EXCEEDED`	429	Too many requests — back off and retry.
`SESSION_EXPIRED`	400	The 24-hour WhatsApp customer service window has expired. Send an approved template instead.
`INVALID_RECIPIENT`	400	The phone number is not a WhatsApp user.
`TEMPLATE_ERROR`	400	The named template was rejected by Meta (wrong language, wrong variable count, not approved, etc).
`UNSUPPORTED_TYPE`	400	Meta does not support this message type for the recipient.
`MEDIA_FETCH_FAILED`	400	We could not download the media URL you supplied; it must be a public HTTPS URL returning bytes.
`MEDIA_UPLOAD_FAILED`	502	Meta rejected our upload of your media bytes.
`IDEMPOTENCY_CONFLICT`	409	Same Idempotency-Key reused with a different request body.
`IDEMPOTENCY_IN_PROGRESS`	409	A previous request with the same Idempotency-Key is still in flight.
`WHATSAPP_ERROR`	502	Meta's WhatsApp API returned an error not covered above.
`INTERNAL_ERROR`	500	An unexpected error occurred on our side.

Account

Telegram messaging is currently dashboard-only — programmatic API coverage is on the roadmap. The endpoints below cover WhatsApp and Email today.

Retrieve information about the workspace and channel tied to your API key.

GET/v1/account

Read · 300/min

bash

curl https://api.247rep.app/v1/account \
  -H "Authorization: Bearer rep_live_your_key"

Response

json

{
  "workspace": { "name": "Acme Inc", "email": "owner@acme.com" },
  "assistant": { "name": "Acme Support", "platform": "WHATSAPP" },
  "whatsappNumber": "+2348012345678",
  "creditsBalance": 4820,
  "environment": "live",
  "messagingTier": "TIER_1K",
  "qualityRating": "GREEN"
}

messagingTier and qualityRating are sourced from Meta and only present when the WhatsApp number is fully connected.

Messages

Send WhatsApp messages and read message history.

POST/v1/messages/send

Send a WhatsApp message to a recipient.

Send · 100/min 1 text · 2 image · 5 video · 2 doc/audio · 2 template

For media (image, video, audio, document) we automatically fetch the URL you provide, upload the bytes to Meta as a private media object, and send the message with that uploaded media ID. Meta's link mode is unreliable in production (Firebase signed URLs and presigned S3 links are often silently rejected), so upload mode is the default. Just give us a public HTTPS link and we handle the rest.

Parameters

to

stringrequired

Recipient phone number in E.164 format (e.g. +2348012345678).

type

enumrequired

One of text, image, audio, video, document, template, interactive, location.

text

objectoptional

{ body } — required when type is text. Max 4096 chars.

image / video / document

objectoptional

{ link, caption?, filename? } — a publicly reachable media URL. We fetch the bytes and re-upload to Meta.

audio

objectoptional

{ link } — a publicly reachable audio URL.

template

objectoptional

{ name, language: { code }, components? } — name must be lowercase alphanumeric + underscores.

location

objectoptional

{ latitude, longitude, name?, address? }.

Set the Idempotency-Key header on every send so a network retry never produces a duplicate message. See Idempotency for details.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "image",
    "image": { "link": "https://example.com/photo.jpg", "caption": "Your order" }
  }'

Send a voice note or audio file

Use type: "audio" with a publicly reachable HTTPS link. WhatsApp supports MP3, OGG (Opus), AAC, AMR, and M4A. Audio costs 2 credits.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "audio",
    "audio": { "link": "https://example.com/welcome.mp3" }
  }'

Response

json

{
  "messageId": "cm5xyz...",
  "whatsappMessageId": "wamid.HBgM...",
  "status": "sent",
  "creditsUsed": 4,
  "creditsRemaining": 4816
}

GET/v1/messages

List messages across all conversations, newest first.

Read · 300/min

Parameters

conversationId

stringoptional

Filter to a single conversation.

direction

stringoptional

inbound or outbound.

status

stringoptional

Filter by delivery status (sent, delivered, read, failed).

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm5...",
      "conversationId": "cm4...",
      "whatsappMessageId": "wamid...",
      "direction": "outbound",
      "senderType": "api",
      "content": "Hello from 247Rep!",
      "contentType": "text",
      "mediaUrl": null,
      "status": "delivered",
      "createdAt": "2026-06-19T10:00:00.000Z",
      "deliveredAt": "2026-06-19T10:00:02.000Z",
      "readAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/messages/{messageId}

Retrieve a single message by ID, including media metadata and credits used.

Read · 300/min

Conversations

List and inspect conversations, fetch their messages, and close them.

GET/v1/conversations

List conversations, newest activity first.

Read · 300/min

Parameters

status

stringoptional

all (default), open, or closed.

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm4...",
      "customerPhone": "+2348012345678",
      "customerName": "Ada",
      "customerEmail": null,
      "customerAvatar": null,
      "status": "active",
      "messageCount": 12,
      "lastMessagePreview": "Thanks!",
      "lastMessageAt": "2026-06-19T09:58:00.000Z",
      "firstMessageAt": "2026-06-10T08:00:00.000Z",
      "createdAt": "2026-06-10T08:00:00.000Z",
      "serviceWindowOpen": true
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

serviceWindowOpen indicates whether the WhatsApp 24-hour customer service window is still open. When closed, you can only send approved template messages.

GET/v1/conversations/{conversationId}

Retrieve a single conversation, including automation and escalation state.

Read · 300/min

GET/v1/conversations/{conversationId}/messages

List the messages within a conversation, newest first.

Read · 300/min

POST/v1/conversations/{conversationId}/close

Mark a conversation as closed.

Send · 100/min

json

{ "success": true, "conversationId": "cm4...", "status": "closed" }

Contacts

Contacts represent customers identified by phone number. Create or update them, list, retrieve, and delete.

GET/v1/contacts

List contacts that have a phone number, newest activity first.

Read · 300/min

POST/v1/contacts

Create a contact, or update the existing one with the same phone number (upsert).

Contacts · 200/min

Parameters

phone

stringrequired

E.164 phone number — the unique key.

name

stringoptional

Display name. Max 200 chars.

email

stringoptional

Contact email address.

tags

string[]optional

Optional list of tags.

metadata

objectoptional

Arbitrary key/value metadata.

bash

curl -X POST https://api.247rep.app/v1/contacts \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+2348012345678", "name": "Ada Lovelace", "email": "ada@example.com" }'

Returns 201 Created for a new contact, or 200 OK when an existing contact was updated.

GET/v1/contacts/{contactId}

Retrieve a single contact.

Read · 300/min

DELETE/v1/contacts/{contactId}

Permanently delete a contact and its conversation history.

Send · 100/min

json

{ "success": true, "deleted": "cm4..." }

Broadcasts

Send a message to many contacts at once. Broadcasts are queued and processed asynchronously.

POST/v1/broadcast

Queue a broadcast to up to 1,000 contacts.

Broadcast · 10/min Per recipient (same cost as the underlying message type)

Parameters

contactIds

string[]required

1–1000 conversation/contact IDs to send to.

message

objectrequired

{ type, text? | image? | template? } where type is text, image, or template.

bash

curl -X POST https://api.247rep.app/v1/broadcast \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cm4a...", "cm4b..."],
    "message": { "type": "text", "text": { "body": "Flash sale today only!" } }
  }'

Response — 202 Accepted

json

{
  "broadcastId": "cm6...",
  "totalRecipients": 2,
  "creditsUsed": 4,
  "status": "sending"
}

GET/v1/broadcast/{broadcastId}

Check the delivery progress of a broadcast.

Read · 300/min

json

{
  "id": "cm6...",
  "message": "Flash sale today only!",
  "totalRecipients": 2,
  "sentCount": 2,
  "failedCount": 0,
  "status": "completed",
  "createdAt": "2026-06-19T10:00:00.000Z",
  "completedAt": "2026-06-19T10:00:30.000Z",
  "delivered": 2,
  "failed": 0,
  "pending": 0
}

Templates

List your approved WhatsApp message templates. Templates are required to message a customer outside the 24-hour service window.

GET/v1/templates

List approved message templates from Meta.

Read · 300/min

json

{
  "data": [
    {
      "name": "order_confirmation",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": [ /* ... */ ]
    }
  ]
}

Only APPROVED templates are returned. Results are cached briefly, so a newly approved template may take a short time to appear.

Telegram — Overview

Telegram endpoints require an API key scoped to a Telegram channel. Using a WhatsApp or email key returns 403 FORBIDDEN.

Telegram is simpler than WhatsApp: there are no approved templates and no 24-hour service window. As long as a user has started a chat with your bot (or your bot is in the group), you can message them any time.

The recipient is a Telegram chat_id (a number) or an @username.
Send text, photos, videos, documents, or audio — each with an optional caption.
No template approvals required, no message category fees.
Delivery is real-time. We use Telegram's native Bot API on your behalf.

Telegram — Send message

One endpoint, five message types. Pick the type and supply the matching media URL.

POST/v1/telegram/send

Send a Telegram message to a chat.

Send · 100/min 1 text · 2 photo · 5 video · 2 doc/audio

Parameters

chatId

string | numberrequired

Telegram chat ID (e.g. 123456789) or @username.

type

enumrequired

One of text, photo, video, document, audio.

text

stringoptional

Required when type is text. Max 4096 chars.

url

stringoptional

Required for photo, video, document, audio. Must be HTTPS and publicly reachable.

caption

stringoptional

Optional caption for media (max 1024 chars).

filename

stringoptional

Optional file name shown for documents.

parseMode

stringoptional

HTML or MarkdownV2. Applies to text/caption.

disableNotification

booleanoptional

Send silently — no push notification.

replyToMessageId

numberoptional

Reply to a specific message in the chat.

Text

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "text",
    "text": "Your order has shipped."
  }'

Photo with caption

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "photo",
    "url": "https://example.com/order.jpg",
    "caption": "Your order"
  }'

Document

json

{
  "chatId": "@mychannel",
  "type": "document",
  "url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf",
  "caption": "Your invoice"
}

Audio (music or voice note)

Use type: "audio" with a publicly reachable HTTPS link. Telegram accepts MP3, M4A, and OGG. Audio costs 2 credits.

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "audio",
    "url": "https://example.com/welcome.mp3",
    "caption": "Welcome message"
  }'

Response

json

{
  "messageId": "cm9...",
  "telegramMessageId": 42,
  "status": "sent",
  "creditsUsed": 4,
  "creditsRemaining": 4812
}

Node example

javascript

const res = await fetch("https://api.247rep.app/v1/telegram/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.REP_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    chatId: 123456789,
    type: "photo",
    url: "https://example.com/order.jpg",
    caption: "Your order",
  }),
});
const data = await res.json();

Python example

python

import os, uuid, requests

r = requests.post(
    "https://api.247rep.app/v1/telegram/send",
    headers={
        "Authorization": f"Bearer {os.environ['REP_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "chatId": 123456789,
        "type": "text",
        "text": "Hello from Python!",
    },
)
print(r.json())

Telegram — Conversations

List Telegram conversations and read their messages.

GET/v1/telegram/conversations

List Telegram conversations, newest activity first.

Read · 300/min

Parameters

status

stringoptional

all (default), open, or closed.

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm8...",
      "telegramChatId": "123456789",
      "telegramUsername": "ada_lovelace",
      "customerName": "Ada",
      "status": "active",
      "messageCount": 4,
      "lastMessagePreview": "thanks!",
      "lastMessageAt": "2026-06-19T09:58:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/telegram/conversations/{conversationId}/messages

List the messages within a Telegram conversation, newest first.

Read · 300/min

Email — Account

Email endpoints require an API key scoped to an email channel. Using a WhatsApp key returns 403 FORBIDDEN.

GET/v1/email/account

Get the connected email account and sync status.

Read · 300/min

json

{
  "emailAddress": "support@acme.com",
  "displayName": "Acme Support",
  "provider": "gmail",
  "syncStatus": "active",
  "lastSyncAt": "2026-06-19T09:59:00.000Z",
  "aiAutoReply": true
}

Email — Send

Send an email from your connected account. Sends immediately (no undo window). The shape mirrors what Resend and similar services offer, so porting existing send code is straightforward.

POST/v1/email/send

Send an email message.

Send · 100/min 1 credit

Parameters

to

string | string[]required

One recipient or an array of recipient email addresses.

subject

stringrequired

Email subject line. Max 998 chars.

html

stringoptional

HTML body. Provide html, text, or both. At least one is required.

text

stringoptional

Plain-text body. Provide html, text, or both.

from

stringoptional

Optional friendly From override. Must use your connected sending address; we rewrite it if not.

replyTo

string | string[]optional

Reply-To address(es).

cc

string | string[]optional

CC recipient(s).

bcc

string | string[]optional

BCC recipient(s).

headers

objectoptional

Extra MIME headers as key/value pairs (e.g. List-Unsubscribe).

attachments

object[]optional

Up to 10 attachments. Each item: { filename, content?: base64, url?: string, contentType? }. 8 MB per attachment, 25 MB total.

inReplyTo

stringoptional

Message-ID this email replies to.

threadId

stringoptional

Append to an existing thread; a new thread is created when omitted.

Older clients can still send bodyHtml / bodyText — these are accepted as aliases for html / text for backward compatibility.

HTML email

bash

curl -X POST https://api.247rep.app/v1/email/send \
  -H "Authorization: Bearer rep_live_your_email_key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your order has shipped",
    "html": "<p>Tracking: <strong>ABC123</strong></p>",
    "text": "Tracking: ABC123"
  }'

Plain text only

json

{
  "to": "customer@example.com",
  "subject": "Quick note",
  "text": "Hi, just confirming your appointment for tomorrow."
}

With an attachment (base64)

json

{
  "to": "customer@example.com",
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJ...",
      "contentType": "application/pdf"
    }
  ]
}

With an attachment (URL)

json

{
  "to": "customer@example.com",
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    { "filename": "invoice.pdf", "url": "https://example.com/invoice.pdf" }
  ]
}

Response

json

{
  "messageId": "<api-1718...@247rep.app>",
  "threadId": "cm7...",
  "status": "sent",
  "creditsUsed": 1,
  "creditsRemaining": 4817
}

Node example

javascript

import crypto from "node:crypto";

const res = await fetch("https://api.247rep.app/v1/email/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.REP_EMAIL_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    to: "customer@example.com",
    subject: "Welcome!",
    html: "<h1>Welcome</h1><p>Thanks for joining.</p>",
    text: "Welcome! Thanks for joining.",
  }),
});
const data = await res.json();

Python example

python

import os, uuid, requests

r = requests.post(
    "https://api.247rep.app/v1/email/send",
    headers={
        "Authorization": f"Bearer {os.environ['REP_EMAIL_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "to": "customer@example.com",
        "subject": "Welcome!",
        "html": "<h1>Welcome</h1><p>Thanks for joining.</p>",
    },
)
print(r.json())

Email — Threads

List email threads with folder and category filters.

GET/v1/email/threads

List email threads, newest activity first.

Read · 300/min

Parameters

folder

stringoptional

inbox (default), starred, sent, drafts, archive, or spam.

category

stringoptional

Filter by AI category.

isRead

booleanoptional

Filter by read state.

limit

integeroptional

Default 20, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm7...",
      "subject": "Refund request",
      "contactEmail": "customer@example.com",
      "contactName": "Ada",
      "lastMessageAt": "2026-06-19T09:00:00.000Z",
      "messageCount": 3,
      "isRead": false,
      "isStarred": false,
      "category": "support",
      "priority": "normal"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/email/threads/{threadId}

Retrieve a single thread with its messages.

Read · 300/min

Email — Contacts

List unique email contacts, aggregated across threads.

GET/v1/email/contacts

List deduplicated email contacts.

Read · 300/min

Parameters

search

stringoptional

Match against contact email or name.

limit

integeroptional

Default 20, max 100.

cursor

stringoptional

Email-based pagination cursor.

json

{
  "data": [
    {
      "email": "customer@example.com",
      "name": "Ada",
      "lastContactDate": "2026-06-19T09:00:00.000Z",
      "messageCount": 5,
      "linkedWhatsAppPhone": "+2348012345678"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Managing webhooks

Register HTTPS endpoints to receive real-time events. WhatsApp and email each have their own webhook endpoints; use the key for the matching channel.

GET/v1/webhooks

List registered WhatsApp webhooks.

Read · 300/min

POST/v1/webhooks

Webhooks · 20/min

Parameters

url

stringrequired

HTTPS endpoint to receive events. Max 2048 chars.

events

string[]required

At least one event type to subscribe to.

secret

stringoptional

Shared secret used to sign deliveries. Max 256 chars.

On registration we send a GET to your URL with a challenge query parameter. Your endpoint must respond with the exact challenge value as plain text, or registration fails with WEBHOOK_VERIFICATION_FAILED.

bash

curl -X POST https://api.247rep.app/v1/webhooks \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/247rep",
    "events": ["message.received", "message.delivered"],
    "secret": "whsec_your_secret"
  }'

json

{
  "id": "cm8...",
  "url": "https://yourapp.com/webhooks/247rep",
  "events": ["message.received", "message.delivered"],
  "isActive": true,
  "createdAt": "2026-06-19T10:00:00.000Z"
}

DELETE/v1/webhooks/{webhookId}

Delete a webhook.

Webhooks · 20/min

Email webhooks

Email channels use the parallel /v1/email/webhooks and /v1/email/webhooks/{webhookId} endpoints with the same request/response shape.

Event types

Subscribe to the events relevant to your integration.

WhatsApp events

Event	Fired when
`message.received`	An inbound message arrives from a customer.
`message.sent`	An outbound message is accepted by WhatsApp.
`message.delivered`	A message is delivered to the recipient's device.
`message.read`	A message is read by the recipient.
`message.failed`	A message fails to send or deliver.

Email events

Event	Fired when
`email.received`	An inbound email arrives.
`email.sent`	An outbound email is sent.
`email.opened`	A sent email is opened by the recipient.
`email.thread.categorized`	The AI assigns a category to a thread.

Payload

Events are delivered as a JSON POST with a consistent envelope:

json

{
  "event": "message.received",
  "timestamp": "2026-06-19T10:00:00.000Z",
  "data": {
    "conversationId": "cm4...",
    "messageId": "wamid...",
    "from": "+2348012345678",
    "content": "Is this in stock?"
  }
}

Verifying signatures

When you register a webhook with a secret, every delivery is signed. Verify the X-247Rep-Signature header — an HMAC-SHA256 of the raw request body using your secret — to confirm the request genuinely came from 247Rep.

typescript

import crypto from "crypto";

function verifySignature(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhooks/247rep", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-247Rep-Signature") || "";
  if (!verifySignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // handle event...
  res.status(200).send("ok");
});

Always respond with a 2xx status within a few seconds. Do heavy processing asynchronously so deliveries are not retried unnecessarily.

Overview

All requests must be made over HTTPS and authenticated with an API key.

JSON request and response bodies
Bearer token authentication with scoped, revocable API keys
Separate test and live environments
Cursor-based pagination on all list endpoints
Per-endpoint rate limiting with standard X-RateLimit-* headers
Real-time webhooks for inbound and delivery events

Base URL

All API endpoints are relative to the following base URL:

text

https://api.247rep.app/v1

For example, to send a WhatsApp message you would issue a POST request to https://api.247rep.app/v1/messages/send.

Test & live modes

Every workspace has two independent API environments, identified by the key prefix. The environment is inferred from the key you authenticate with — there is no separate header.

Prefix	Mode	Behaviour
`rep_live_…`	Live	Sends real messages and deducts real credits.
`rep_test_…`	Test	Validates and authenticates exactly like live, but never sends a real message and never deducts credits. Mutating endpoints return a mock response with test: true.

Use a test key in development and CI. Test-mode send and broadcast calls return a synthetic messageId/broadcastId and creditsUsed: 0.

API keys

Keys are shown in full only once at creation. 247Rep stores only a SHA-256 hash, so a lost key cannot be recovered — generate a new one instead.

Authorization header

Pass your key as a bearer token in the Authorization header on every request:

http

Authorization: Bearer rep_live_your_key_here

A request with a missing, malformed, or revoked key returns 401 Unauthorized:

json

{
  "code": "INVALID_KEY",
  "message": "Invalid API key"
}

Quick start

Send your first WhatsApp message in one request. Replace the key and recipient with your own.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": { "body": "Hello from 247Rep!" }
  }'

typescript

const res = await fetch("https://api.247rep.app/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer rep_live_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+2348012345678",
    type: "text",
    text: { body: "Hello from 247Rep!" },
  }),
});
const data = await res.json();

python

import requests

res = requests.post(
    "https://api.247rep.app/v1/messages/send",
    headers={"Authorization": "Bearer rep_live_your_key"},
    json={
        "to": "+2348012345678",
        "type": "text",
        "text": {"body": "Hello from 247Rep!"},
    },
)
data = res.json()

Pagination

Parameters

limit

integeroptional

Items per page. Default 50, maximum 100.

cursor

stringoptional

The nextCursor returned by the previous page.

json

{
  "data": [ /* ... items ... */ ],
  "hasMore": true,
  "nextCursor": "cm5a1b2c3d4e5f6g7h8i9j0k"
}

Rate limits

Rate limits are applied per API key and vary by endpoint category. A global burst limit of 20 requests/second also applies across all endpoints.

Category	Limit	Applies to
Send	100 / min	Sending messages, closing conversations, deleting contacts
Broadcast	10 / min	Broadcast sends
Contacts (write)	200 / min	Creating / upserting contacts
Read	300 / min	All GET endpoints
Webhooks	20 / min	Creating / deleting webhooks
Burst	20 / sec	All endpoints (global)

New API keys are limited to 30 send/min and 5 broadcast/min for their first 7 days. These tighten abuse risk on fresh keys and lift automatically afterward.

Every response includes the current limit state:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1718745600

When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header (seconds):

json

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please retry after the specified time."
}

Idempotency

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Idempotency-Key: 8c3d2f60-4e6e-4b4e-9a5d-1d92f1d8d8a1" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": { "body": "Hello" }
  }'

How it behaves

First request with a given key runs normally and we cache the response for 24 hours.
Any retry within 24 hours that reuses the same key replays the original response with header Idempotent-Replayed: true. No duplicate send, no duplicate credit charge.
If a retry sends a different body with the same key, we return 409 Conflict with code IDEMPOTENCY_CONFLICT. Use a fresh key for a different payload.
If two requests with the same key arrive at the same time, the second one gets 409 with code IDEMPOTENCY_IN_PROGRESS. Wait a moment and retry.

Always generate the key on YOUR server, not the client. That way a flaky browser retry never starts a second message.

Credits & costs

Sending messages consumes credits from your workspace balance. The cost depends on the channel and the message type. Read endpoints are free. Inbound messages are free.

Channel	Action	Cost
WhatsApp / Telegram	Text message	1 credit
WhatsApp / Telegram	Image	2 credits
WhatsApp / Telegram	Video	5 credits
WhatsApp / Telegram	Document or audio	2 credits
WhatsApp	Template message	2 credits
Email	Any email (with or without attachments)	1 credit
WhatsApp	Broadcast	Per recipient (same as the underlying message type)

Errors

247Rep uses conventional HTTP status codes. 2xx indicates success, 4xx a problem with the request, and 5xx a server error. Every error body has the same shape:

json

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. Required: 2, available: 0",
  "docs": "https://docs.247rep.com/errors#INSUFFICIENT_CREDITS"
}

Code	HTTP	Meaning
`INVALID_AUTH`	401	Missing or malformed Authorization header.
`INVALID_KEY`	401	The API key does not exist or has the wrong format.
`REVOKED_KEY`	401	The API key has been revoked.
`FORBIDDEN`	403	Key not authorized for this resource (e.g. email endpoints require an email channel key).
`INSUFFICIENT_CREDITS`	402	Workspace balance is too low for this action.
`VALIDATION_ERROR`	400	The request body failed validation.
`NOT_CONFIGURED`	400	WhatsApp is not configured for this channel.
`NO_RECIPIENTS`	400	No valid recipients were found for a broadcast.
`WEBHOOK_VERIFICATION_FAILED`	400	Your endpoint did not echo the verification challenge.
`NOT_FOUND`	404	The requested resource does not exist.
`RATE_LIMIT_EXCEEDED`	429	Too many requests — back off and retry.
`SESSION_EXPIRED`	400	The 24-hour WhatsApp customer service window has expired. Send an approved template instead.
`INVALID_RECIPIENT`	400	The phone number is not a WhatsApp user.
`TEMPLATE_ERROR`	400	The named template was rejected by Meta (wrong language, wrong variable count, not approved, etc).
`UNSUPPORTED_TYPE`	400	Meta does not support this message type for the recipient.
`MEDIA_FETCH_FAILED`	400	We could not download the media URL you supplied; it must be a public HTTPS URL returning bytes.
`MEDIA_UPLOAD_FAILED`	502	Meta rejected our upload of your media bytes.
`IDEMPOTENCY_CONFLICT`	409	Same Idempotency-Key reused with a different request body.
`IDEMPOTENCY_IN_PROGRESS`	409	A previous request with the same Idempotency-Key is still in flight.
`WHATSAPP_ERROR`	502	Meta's WhatsApp API returned an error not covered above.
`INTERNAL_ERROR`	500	An unexpected error occurred on our side.

Account

Telegram messaging is currently dashboard-only — programmatic API coverage is on the roadmap. The endpoints below cover WhatsApp and Email today.

Retrieve information about the workspace and channel tied to your API key.

GET/v1/account

Read · 300/min

bash

curl https://api.247rep.app/v1/account \
  -H "Authorization: Bearer rep_live_your_key"

Response

json

{
  "workspace": { "name": "Acme Inc", "email": "owner@acme.com" },
  "assistant": { "name": "Acme Support", "platform": "WHATSAPP" },
  "whatsappNumber": "+2348012345678",
  "creditsBalance": 4820,
  "environment": "live",
  "messagingTier": "TIER_1K",
  "qualityRating": "GREEN"
}

messagingTier and qualityRating are sourced from Meta and only present when the WhatsApp number is fully connected.

Messages

Send WhatsApp messages and read message history.

POST/v1/messages/send

Send a WhatsApp message to a recipient.

Send · 100/min 1 text · 2 image · 5 video · 2 doc/audio · 2 template

Parameters

to

stringrequired

Recipient phone number in E.164 format (e.g. +2348012345678).

type

enumrequired

One of text, image, audio, video, document, template, interactive, location.

text

objectoptional

{ body } — required when type is text. Max 4096 chars.

image / video / document

objectoptional

{ link, caption?, filename? } — a publicly reachable media URL. We fetch the bytes and re-upload to Meta.

audio

objectoptional

{ link } — a publicly reachable audio URL.

template

objectoptional

{ name, language: { code }, components? } — name must be lowercase alphanumeric + underscores.

location

objectoptional

{ latitude, longitude, name?, address? }.

Set the Idempotency-Key header on every send so a network retry never produces a duplicate message. See Idempotency for details.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "image",
    "image": { "link": "https://example.com/photo.jpg", "caption": "Your order" }
  }'

Send a voice note or audio file

Use type: "audio" with a publicly reachable HTTPS link. WhatsApp supports MP3, OGG (Opus), AAC, AMR, and M4A. Audio costs 2 credits.

bash

curl -X POST https://api.247rep.app/v1/messages/send \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "audio",
    "audio": { "link": "https://example.com/welcome.mp3" }
  }'

Response

json

{
  "messageId": "cm5xyz...",
  "whatsappMessageId": "wamid.HBgM...",
  "status": "sent",
  "creditsUsed": 4,
  "creditsRemaining": 4816
}

GET/v1/messages

List messages across all conversations, newest first.

Read · 300/min

Parameters

conversationId

stringoptional

Filter to a single conversation.

direction

stringoptional

inbound or outbound.

status

stringoptional

Filter by delivery status (sent, delivered, read, failed).

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm5...",
      "conversationId": "cm4...",
      "whatsappMessageId": "wamid...",
      "direction": "outbound",
      "senderType": "api",
      "content": "Hello from 247Rep!",
      "contentType": "text",
      "mediaUrl": null,
      "status": "delivered",
      "createdAt": "2026-06-19T10:00:00.000Z",
      "deliveredAt": "2026-06-19T10:00:02.000Z",
      "readAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/messages/{messageId}

Retrieve a single message by ID, including media metadata and credits used.

Read · 300/min

Conversations

List and inspect conversations, fetch their messages, and close them.

GET/v1/conversations

List conversations, newest activity first.

Read · 300/min

Parameters

status

stringoptional

all (default), open, or closed.

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm4...",
      "customerPhone": "+2348012345678",
      "customerName": "Ada",
      "customerEmail": null,
      "customerAvatar": null,
      "status": "active",
      "messageCount": 12,
      "lastMessagePreview": "Thanks!",
      "lastMessageAt": "2026-06-19T09:58:00.000Z",
      "firstMessageAt": "2026-06-10T08:00:00.000Z",
      "createdAt": "2026-06-10T08:00:00.000Z",
      "serviceWindowOpen": true
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

serviceWindowOpen indicates whether the WhatsApp 24-hour customer service window is still open. When closed, you can only send approved template messages.

GET/v1/conversations/{conversationId}

Retrieve a single conversation, including automation and escalation state.

Read · 300/min

GET/v1/conversations/{conversationId}/messages

List the messages within a conversation, newest first.

Read · 300/min

POST/v1/conversations/{conversationId}/close

Mark a conversation as closed.

Send · 100/min

json

{ "success": true, "conversationId": "cm4...", "status": "closed" }

Contacts

Contacts represent customers identified by phone number. Create or update them, list, retrieve, and delete.

GET/v1/contacts

List contacts that have a phone number, newest activity first.

Read · 300/min

POST/v1/contacts

Create a contact, or update the existing one with the same phone number (upsert).

Contacts · 200/min

Parameters

phone

stringrequired

E.164 phone number — the unique key.

name

stringoptional

Display name. Max 200 chars.

email

stringoptional

Contact email address.

tags

string[]optional

Optional list of tags.

metadata

objectoptional

Arbitrary key/value metadata.

bash

curl -X POST https://api.247rep.app/v1/contacts \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+2348012345678", "name": "Ada Lovelace", "email": "ada@example.com" }'

Returns 201 Created for a new contact, or 200 OK when an existing contact was updated.

GET/v1/contacts/{contactId}

Retrieve a single contact.

Read · 300/min

DELETE/v1/contacts/{contactId}

Permanently delete a contact and its conversation history.

Send · 100/min

json

{ "success": true, "deleted": "cm4..." }

Broadcasts

Send a message to many contacts at once. Broadcasts are queued and processed asynchronously.

POST/v1/broadcast

Queue a broadcast to up to 1,000 contacts.

Broadcast · 10/min Per recipient (same cost as the underlying message type)

Parameters

contactIds

string[]required

1–1000 conversation/contact IDs to send to.

message

objectrequired

{ type, text? | image? | template? } where type is text, image, or template.

bash

curl -X POST https://api.247rep.app/v1/broadcast \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cm4a...", "cm4b..."],
    "message": { "type": "text", "text": { "body": "Flash sale today only!" } }
  }'

Response — 202 Accepted

json

{
  "broadcastId": "cm6...",
  "totalRecipients": 2,
  "creditsUsed": 4,
  "status": "sending"
}

GET/v1/broadcast/{broadcastId}

Check the delivery progress of a broadcast.

Read · 300/min

json

{
  "id": "cm6...",
  "message": "Flash sale today only!",
  "totalRecipients": 2,
  "sentCount": 2,
  "failedCount": 0,
  "status": "completed",
  "createdAt": "2026-06-19T10:00:00.000Z",
  "completedAt": "2026-06-19T10:00:30.000Z",
  "delivered": 2,
  "failed": 0,
  "pending": 0
}

Templates

List your approved WhatsApp message templates. Templates are required to message a customer outside the 24-hour service window.

GET/v1/templates

List approved message templates from Meta.

Read · 300/min

json

{
  "data": [
    {
      "name": "order_confirmation",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": [ /* ... */ ]
    }
  ]
}

Only APPROVED templates are returned. Results are cached briefly, so a newly approved template may take a short time to appear.

Telegram — Overview

Telegram endpoints require an API key scoped to a Telegram channel. Using a WhatsApp or email key returns 403 FORBIDDEN.

The recipient is a Telegram chat_id (a number) or an @username.
Send text, photos, videos, documents, or audio — each with an optional caption.
No template approvals required, no message category fees.
Delivery is real-time. We use Telegram's native Bot API on your behalf.

Telegram — Send message

One endpoint, five message types. Pick the type and supply the matching media URL.

POST/v1/telegram/send

Send a Telegram message to a chat.

Send · 100/min 1 text · 2 photo · 5 video · 2 doc/audio

Parameters

chatId

string | numberrequired

Telegram chat ID (e.g. 123456789) or @username.

type

enumrequired

One of text, photo, video, document, audio.

text

stringoptional

Required when type is text. Max 4096 chars.

url

stringoptional

Required for photo, video, document, audio. Must be HTTPS and publicly reachable.

caption

stringoptional

Optional caption for media (max 1024 chars).

filename

stringoptional

Optional file name shown for documents.

parseMode

stringoptional

HTML or MarkdownV2. Applies to text/caption.

disableNotification

booleanoptional

Send silently — no push notification.

replyToMessageId

numberoptional

Reply to a specific message in the chat.

Text

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "text",
    "text": "Your order has shipped."
  }'

Photo with caption

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "photo",
    "url": "https://example.com/order.jpg",
    "caption": "Your order"
  }'

Document

json

{
  "chatId": "@mychannel",
  "type": "document",
  "url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf",
  "caption": "Your invoice"
}

Audio (music or voice note)

Use type: "audio" with a publicly reachable HTTPS link. Telegram accepts MP3, M4A, and OGG. Audio costs 2 credits.

bash

curl -X POST https://api.247rep.app/v1/telegram/send \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 123456789,
    "type": "audio",
    "url": "https://example.com/welcome.mp3",
    "caption": "Welcome message"
  }'

Response

json

{
  "messageId": "cm9...",
  "telegramMessageId": 42,
  "status": "sent",
  "creditsUsed": 4,
  "creditsRemaining": 4812
}

Node example

javascript

const res = await fetch("https://api.247rep.app/v1/telegram/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.REP_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    chatId: 123456789,
    type: "photo",
    url: "https://example.com/order.jpg",
    caption: "Your order",
  }),
});
const data = await res.json();

Python example

python

import os, uuid, requests

r = requests.post(
    "https://api.247rep.app/v1/telegram/send",
    headers={
        "Authorization": f"Bearer {os.environ['REP_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "chatId": 123456789,
        "type": "text",
        "text": "Hello from Python!",
    },
)
print(r.json())

Telegram — Conversations

List Telegram conversations and read their messages.

GET/v1/telegram/conversations

List Telegram conversations, newest activity first.

Read · 300/min

Parameters

status

stringoptional

all (default), open, or closed.

limit

integeroptional

Default 50, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm8...",
      "telegramChatId": "123456789",
      "telegramUsername": "ada_lovelace",
      "customerName": "Ada",
      "status": "active",
      "messageCount": 4,
      "lastMessagePreview": "thanks!",
      "lastMessageAt": "2026-06-19T09:58:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/telegram/conversations/{conversationId}/messages

List the messages within a Telegram conversation, newest first.

Read · 300/min

Email — Account

Email endpoints require an API key scoped to an email channel. Using a WhatsApp key returns 403 FORBIDDEN.

GET/v1/email/account

Get the connected email account and sync status.

Read · 300/min

json

{
  "emailAddress": "support@acme.com",
  "displayName": "Acme Support",
  "provider": "gmail",
  "syncStatus": "active",
  "lastSyncAt": "2026-06-19T09:59:00.000Z",
  "aiAutoReply": true
}

Email — Send

Send an email from your connected account. Sends immediately (no undo window). The shape mirrors what Resend and similar services offer, so porting existing send code is straightforward.

POST/v1/email/send

Send an email message.

Send · 100/min 1 credit

Parameters

to

string | string[]required

One recipient or an array of recipient email addresses.

subject

stringrequired

Email subject line. Max 998 chars.

html

stringoptional

HTML body. Provide html, text, or both. At least one is required.

text

stringoptional

Plain-text body. Provide html, text, or both.

from

stringoptional

Optional friendly From override. Must use your connected sending address; we rewrite it if not.

replyTo

string | string[]optional

Reply-To address(es).

cc

string | string[]optional

CC recipient(s).

bcc

string | string[]optional

BCC recipient(s).

headers

objectoptional

Extra MIME headers as key/value pairs (e.g. List-Unsubscribe).

attachments

object[]optional

Up to 10 attachments. Each item: { filename, content?: base64, url?: string, contentType? }. 8 MB per attachment, 25 MB total.

inReplyTo

stringoptional

Message-ID this email replies to.

threadId

stringoptional

Append to an existing thread; a new thread is created when omitted.

Older clients can still send bodyHtml / bodyText — these are accepted as aliases for html / text for backward compatibility.

HTML email

bash

curl -X POST https://api.247rep.app/v1/email/send \
  -H "Authorization: Bearer rep_live_your_email_key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your order has shipped",
    "html": "<p>Tracking: <strong>ABC123</strong></p>",
    "text": "Tracking: ABC123"
  }'

Plain text only

json

{
  "to": "customer@example.com",
  "subject": "Quick note",
  "text": "Hi, just confirming your appointment for tomorrow."
}

With an attachment (base64)

json

{
  "to": "customer@example.com",
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJ...",
      "contentType": "application/pdf"
    }
  ]
}

With an attachment (URL)

json

{
  "to": "customer@example.com",
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    { "filename": "invoice.pdf", "url": "https://example.com/invoice.pdf" }
  ]
}

Response

json

{
  "messageId": "<api-1718...@247rep.app>",
  "threadId": "cm7...",
  "status": "sent",
  "creditsUsed": 1,
  "creditsRemaining": 4817
}

Node example

javascript

import crypto from "node:crypto";

const res = await fetch("https://api.247rep.app/v1/email/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.REP_EMAIL_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    to: "customer@example.com",
    subject: "Welcome!",
    html: "<h1>Welcome</h1><p>Thanks for joining.</p>",
    text: "Welcome! Thanks for joining.",
  }),
});
const data = await res.json();

Python example

python

import os, uuid, requests

r = requests.post(
    "https://api.247rep.app/v1/email/send",
    headers={
        "Authorization": f"Bearer {os.environ['REP_EMAIL_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "to": "customer@example.com",
        "subject": "Welcome!",
        "html": "<h1>Welcome</h1><p>Thanks for joining.</p>",
    },
)
print(r.json())

Email — Threads

List email threads with folder and category filters.

GET/v1/email/threads

List email threads, newest activity first.

Read · 300/min

Parameters

folder

stringoptional

inbox (default), starred, sent, drafts, archive, or spam.

category

stringoptional

Filter by AI category.

isRead

booleanoptional

Filter by read state.

limit

integeroptional

Default 20, max 100.

cursor

stringoptional

Pagination cursor.

json

{
  "data": [
    {
      "id": "cm7...",
      "subject": "Refund request",
      "contactEmail": "customer@example.com",
      "contactName": "Ada",
      "lastMessageAt": "2026-06-19T09:00:00.000Z",
      "messageCount": 3,
      "isRead": false,
      "isStarred": false,
      "category": "support",
      "priority": "normal"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/email/threads/{threadId}

Retrieve a single thread with its messages.

Read · 300/min

Email — Contacts

List unique email contacts, aggregated across threads.

GET/v1/email/contacts

List deduplicated email contacts.

Read · 300/min

Parameters

search

stringoptional

Match against contact email or name.

limit

integeroptional

Default 20, max 100.

cursor

stringoptional

Email-based pagination cursor.

json

{
  "data": [
    {
      "email": "customer@example.com",
      "name": "Ada",
      "lastContactDate": "2026-06-19T09:00:00.000Z",
      "messageCount": 5,
      "linkedWhatsAppPhone": "+2348012345678"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Managing webhooks

Register HTTPS endpoints to receive real-time events. WhatsApp and email each have their own webhook endpoints; use the key for the matching channel.

GET/v1/webhooks

List registered WhatsApp webhooks.

Read · 300/min

POST/v1/webhooks

Webhooks · 20/min

Parameters

url

stringrequired

HTTPS endpoint to receive events. Max 2048 chars.

events

string[]required

At least one event type to subscribe to.

secret

stringoptional

Shared secret used to sign deliveries. Max 256 chars.

bash

curl -X POST https://api.247rep.app/v1/webhooks \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/247rep",
    "events": ["message.received", "message.delivered"],
    "secret": "whsec_your_secret"
  }'

json

{
  "id": "cm8...",
  "url": "https://yourapp.com/webhooks/247rep",
  "events": ["message.received", "message.delivered"],
  "isActive": true,
  "createdAt": "2026-06-19T10:00:00.000Z"
}

DELETE/v1/webhooks/{webhookId}

Delete a webhook.

Webhooks · 20/min

Email webhooks

Email channels use the parallel /v1/email/webhooks and /v1/email/webhooks/{webhookId} endpoints with the same request/response shape.

Event types

Subscribe to the events relevant to your integration.

WhatsApp events

Event	Fired when
`message.received`	An inbound message arrives from a customer.
`message.sent`	An outbound message is accepted by WhatsApp.
`message.delivered`	A message is delivered to the recipient's device.
`message.read`	A message is read by the recipient.
`message.failed`	A message fails to send or deliver.

Email events

Event	Fired when
`email.received`	An inbound email arrives.
`email.sent`	An outbound email is sent.
`email.opened`	A sent email is opened by the recipient.
`email.thread.categorized`	The AI assigns a category to a thread.

Payload

Events are delivered as a JSON POST with a consistent envelope:

json

{
  "event": "message.received",
  "timestamp": "2026-06-19T10:00:00.000Z",
  "data": {
    "conversationId": "cm4...",
    "messageId": "wamid...",
    "from": "+2348012345678",
    "content": "Is this in stock?"
  }
}

Verifying signatures

typescript

import crypto from "crypto";

function verifySignature(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhooks/247rep", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-247Rep-Signature") || "";
  if (!verifySignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // handle event...
  res.status(200).send("ok");
});

Always respond with a 2xx status within a few seconds. Do heavy processing asynchronously so deliveries are not retried unnecessarily.

247RepREST API

Overview

Base URL

Test & live modes

API keys

Authorization header

Quick start

Pagination

Parameters

Rate limits

Idempotency

How it behaves

Credits & costs

Errors

Account

Response

Messages

Parameters

Send a voice note or audio file

Response

Parameters

Conversations

Parameters

Contacts

Parameters

Broadcasts

Parameters

Response — 202 Accepted

Templates

Telegram — Overview

Telegram — Send message

Parameters

Text

Photo with caption

Document

Audio (music or voice note)

Response

Node example

Python example

Telegram — Conversations

Parameters

Email — Account

Email — Send

Parameters

HTML email

Plain text only

With an attachment (base64)

With an attachment (URL)

Response

Node example

Python example

Email — Threads

Parameters

Email — Contacts

Parameters

Managing webhooks

Parameters

Email webhooks

Event types

WhatsApp events

Email events

Payload

Verifying signatures

Join our newsletter

247RepREST API

Overview

Base URL

Test & live modes

API keys

Authorization header

Quick start

Pagination

Parameters

Rate limits

Idempotency

How it behaves

Credits & costs

Errors

Account

Response

247Rep
REST API

247Rep
REST API