API REFERENCE

247Rep
REST API

Name: 247Rep
Price: 1000 NGN
Availability: InStock
Author: 247Rep

A RESTful API to send messages, manage conversations and contacts, run broadcasts, send email, and receive real-time webhooks. Predictable resource-oriented URLs, JSON request and response bodies, and standard HTTP status codes.

Quick start Product docs

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

Building with an AI agent or codegen? A machine-readable OpenAPI 3.1 spec and a plaintext llms.txt cover this whole API — point your tools at those.

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	Media — a link you host	1 credit (any type)
WhatsApp / Telegram	Media — uploaded to us (image/photo)	2 credits
WhatsApp / Telegram	Media — uploaded to us (video)	5 credits
WhatsApp / Telegram	Media — uploaded to us (document/audio)	2 credits
WhatsApp	Template message	2 credits
Any	Uploading a file to /v1/media	Free
Email	Any email (with or without attachments)	1 credit
WhatsApp	Broadcast	Per recipient (same as the underlying message type)

Media pricing depends on who hosts the file. Pass a public link you host and it's a flat 1 credit (we don't store it). Upload the file to /v1/media and the send is billed by type, because we store and re-serve it. See Messages → Two ways to attach media.

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

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

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

id is the stable account/workspace identifier this key belongs to, and assistantId is the channel it drives — key your integration on these rather than the email, which can change. keyId tells you which key made the call.

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 · media 1 (your link) or 2/5 (uploaded) · 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.

Two ways to attach media

You can either point us at a file you host, or upload it to us — so you never have to expose your own storage publicly.

You host it (flat 1 credit) — pass a public HTTPS link to your own file. We don't store it, so any media type is a flat 1 credit.
We host it (billed by type) — upload the bytes to POST /v1/media, get back a hosted url, then send that url. Because we store and re-serve it, the send is billed by type (image 2 · video 5 · doc/audio 2).

POST/v1/media

Upload a file (multipart/form-data, field 'file', max 25MB) and get a hosted URL. Uploading is free — the send that uses the URL is billed by type.

Send · 100/min Free (upload)

bash

# 1. Upload the file to us (no need to expose your own storage)
curl -X POST https://api.247rep.app/v1/media \
  -H "Authorization: Bearer rep_live_your_key" \
  -F "file=@invoice.pdf"
# → { "url": "https://...vercel-storage.com/247rep-api-media/.../invoice.pdf",
#     "mimeType": "application/pdf", "size": 51234, "filename": "invoice.pdf" }

# 2. Send it — reference the hosted url (billed by type)
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": "document",
    "document": { "link": "https://...vercel-storage.com/247rep-api-media/.../invoice.pdf", "filename": "invoice.pdf" }
  }'

The same /v1/media url works for Telegram too — pass it as url on /v1/telegram/send.

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? }.

replyTo

stringoptional

Optional. Reply to an earlier message as a WhatsApp quoted reply. Pass the message id you got from a webhook or GET /v1/messages (a raw wamid also works). Ignored for template sends.

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

Reply to a message

Add replyTo to any send to thread it as a WhatsApp quoted reply under an earlier message. Use the message id you received from the message.received webhook or GET /v1/messages (the raw wamid works too). It only applies to conversational types — template sends can't be quoted.

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": "Thanks — that works for me!" },
    "replyTo": "cm5_the_message_you_are_replying_to"
  }'

POST/v1/messages/{messageId}/react

React to a message with an emoji — the same affordance as the dashboard.

Send · 100/min Free

messageId is the 247Rep message id (from a webhook or GET /v1/messages). Send an empty emoji to remove a reaction you previously sent.

bash

# Add a reaction
curl -X POST https://api.247rep.app/v1/messages/cm5.../react \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

# Remove it
curl -X POST https://api.247rep.app/v1/messages/cm5.../react \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "" }'

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",
      "referral": null,
      "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.

Ad attribution (Click-to-WhatsApp)

When a customer reaches the business by tapping a Click-to-WhatsApp ad (or a post call-to-action), the conversation carries a referral object describing the ad they came from. It is null for conversations that did not originate from an ad, and is present on both GET /v1/conversations and GET /v1/conversations/{conversationId}.

json

"referral": {
  "source_type": "ad",
  "source_id": "120209...",              // Meta ad id — the ad this lead came from
  "source_url": "https://fb.me/...",
  "headline": "50% off this weekend",
  "body": "Message us to claim your code",
  "media_type": "image",
  "image_url": "https://...",
  "ctwa_clid": "ARB2...",                // click id for Meta's Conversions API
  "captured_at": "2026-06-10T08:00:00.000Z"
}

Parameters

source_id

stringoptional

The Meta ad id — use this to attribute the lead to a specific ad or campaign.

source_type

stringoptional

ad or post.

source_url

stringoptional

The ad / post link the customer tapped.

headline

stringoptional

Ad headline, when provided by Meta.

body

stringoptional

Ad body copy, when provided by Meta.

media_type

stringoptional

image or video, when the ad has media.

image_url / video_url / thumbnail_url

stringoptional

Ad creative URLs, when present.

ctwa_clid

stringoptional

Click id you can forward to Meta's Conversions API to report conversions and optimize the ad.

captured_at

stringoptional

ISO-8601 timestamp of when the referral was captured.

Meta only sends referral data on the first message of an ad-originated conversation, so it is captured once at the conversation origin. Individual fields may be absent depending on the ad; only source_id, source_url, or ctwa_clid is guaranteed when a referral is present.

GET/v1/conversations/{conversationId}

Retrieve a single conversation, including automation and escalation state.

Read · 300/min

PATCH/v1/conversations/{conversationId}

Update a conversation. Set automationEnabled to pause or resume AI auto-reply on this thread.

Send · 100/min

Parameters

automationEnabled

booleanoptional

false pauses the AI on this conversation so a human can take over; true hands it back to the AI. Same toggle as the dashboard.

bash

# Pause the AI on this conversation (a human takes over)
curl -X PATCH https://api.247rep.app/v1/conversations/cm4.../ \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "automationEnabled": false }'

# → { "success": true, "id": "cm4...", "automationEnabled": false, "status": "active" }

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 numeric Telegram chatId (e.g. 123456789) — not a phone number and not a user’s @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.

How to get a chatId. Telegram bots can only message a user who has started the bot first — you can’t cold-message anyone. You get their chatId from an inbound message: the message.received webhook, or GET /v1/telegram/conversations (the telegramChatId field). Reply using that id. An @channelusername works only for public channels your bot administers, never for individual users.

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 · media 1 (your url) or 2/5 (uploaded)

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.

replyTo

stringoptional

Optional. Reply to an earlier message. Pass the 247Rep message id (from a webhook or GET /v1/telegram/conversations/{id}/messages) or Telegram's numeric message_id — resolved within this 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())

Reply to a message

Add replyTo to thread a send under an earlier message. Because Telegram message ids are only unique within a chat, we resolve it against the chatId you send — pass the 247Rep message id (from the message.received webhook or the conversation messages endpoint) or Telegram's numeric message_id.

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": "On it — shipping today!",
    "replyTo": "cm9_or_the_numeric_message_id"
  }'

POST/v1/telegram/messages/{messageId}/react

React to a Telegram message with an emoji (setMessageReaction).

Send · 100/min Free

messageId is the 247Rep message id. Send an empty emoji to remove your reaction. Telegram only accepts a fixed set of reaction emoji (👍 👎 ❤️ 🔥 🥰 👏 😁 🤔 🎉 …); an unsupported emoji returns a 400.

bash

curl -X POST https://api.247rep.app/v1/telegram/messages/cm9.../react \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "🔥" }'

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.

Data Connections — let the AI call your API

The REST API above is your app calling 247Rep. Data Connections are the reverse: 247Rep calling your app. You register your own API once, describe its endpoints in plain language, and the AI calls them live inside a conversation — so “where's my order?” hits your tracking system and the assistant answers with the real, current status.

Data Connections are configured in the dashboard, not over the REST API — go to Dashboard → Data Connections → New Connection. No public database or webhook of your own is required; the AI calls your endpoints on demand, server-side, and every call is logged.

Six auth types are supported, secrets are encrypted at rest (AES-256-GCM), requests are SSRF-guarded and rate-limited per connection, and every call is written to a log you can inspect.

Setup steps

The New Connection wizard walks through four steps, then you add one or more endpoints.

Details — give the connection a name and description, set the base URL of your API (e.g. https://api.yourstore.com), and optionally tune the request timeout and per-minute rate limit.
Auth — choose how we authenticate to your API (see Auth types) and paste the credential. It's encrypted before it ever touches the database.
Test — we make a live call to confirm the base URL and credentials work before anything is saved.
Add endpoints — for each action the AI should be able to take, define:
- Method + path — e.g. GET /orders/{orderId}.
- Parameters — path, query, and request-body fields the AI should fill in.
- Response mapping — which fields of your response the AI should read back (so it quotes the tracking number, not the raw JSON).
- Context instructions — plain-English guidance telling the AI when and how to use this endpoint (“call this when a customer asks about an order status; ask for their order number first”).
- Contact identifier — which field identifies the customer (e.g. their phone), so the AI looks up the right person automatically.

Good context instructions are the difference between an endpoint the AI uses correctly and one it ignores or misuses. Be explicit about the trigger (“when the customer asks X”) and any input it must collect first.

Auth types

Pick whichever matches how your API authenticates. The credential is encrypted at rest.

Supported auth

none

—optional

Public endpoint, no credentials.

bearer

tokenoptional

Sends Authorization: Bearer <token>.

api_key_header

keyoptional

Sends your key in a custom header (you choose the header name).

api_key_query

keyoptional

Appends your key as a query-string parameter.

basic_auth

user/passoptional

HTTP Basic auth with a username and password.

oauth2_client_credentials

client id/secretoptional

We fetch and refresh an access token using the OAuth2 client-credentials grant.

custom_header

headeroptional

Any fixed custom header you specify (name + value).

Need help wiring a specific system? The Integrations page lists the pre-built ones (Shopify, Google, Zapier); anything else is a Data Connection.

API REFERENCE

247Rep
REST API

Quick start Product docs

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

Building with an AI agent or codegen? A machine-readable OpenAPI 3.1 spec and a plaintext llms.txt cover this whole API — point your tools at those.

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	Media — a link you host	1 credit (any type)
WhatsApp / Telegram	Media — uploaded to us (image/photo)	2 credits
WhatsApp / Telegram	Media — uploaded to us (video)	5 credits
WhatsApp / Telegram	Media — uploaded to us (document/audio)	2 credits
WhatsApp	Template message	2 credits
Any	Uploading a file to /v1/media	Free
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

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

{
  "id": "clx9a8b7c6d5e4f3",
  "assistantId": "cma1b2c3d4e5f6g7",
  "keyId": "key_abc123",
  "workspace": { "id": "clx9a8b7c6d5e4f3", "name": "Acme Inc", "email": "owner@acme.com" },
  "assistant": { "id": "cma1b2c3d4e5f6g7", "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 · media 1 (your link) or 2/5 (uploaded) · 2 template

Two ways to attach media

You can either point us at a file you host, or upload it to us — so you never have to expose your own storage publicly.

You host it (flat 1 credit) — pass a public HTTPS link to your own file. We don't store it, so any media type is a flat 1 credit.
We host it (billed by type) — upload the bytes to POST /v1/media, get back a hosted url, then send that url. Because we store and re-serve it, the send is billed by type (image 2 · video 5 · doc/audio 2).

POST/v1/media

Upload a file (multipart/form-data, field 'file', max 25MB) and get a hosted URL. Uploading is free — the send that uses the URL is billed by type.

Send · 100/min Free (upload)

bash

# 1. Upload the file to us (no need to expose your own storage)
curl -X POST https://api.247rep.app/v1/media \
  -H "Authorization: Bearer rep_live_your_key" \
  -F "file=@invoice.pdf"
# → { "url": "https://...vercel-storage.com/247rep-api-media/.../invoice.pdf",
#     "mimeType": "application/pdf", "size": 51234, "filename": "invoice.pdf" }

# 2. Send it — reference the hosted url (billed by type)
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": "document",
    "document": { "link": "https://...vercel-storage.com/247rep-api-media/.../invoice.pdf", "filename": "invoice.pdf" }
  }'

The same /v1/media url works for Telegram too — pass it as url on /v1/telegram/send.

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? }.

replyTo

stringoptional

Optional. Reply to an earlier message as a WhatsApp quoted reply. Pass the message id you got from a webhook or GET /v1/messages (a raw wamid also works). Ignored for template sends.

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

Reply to a message

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": "Thanks — that works for me!" },
    "replyTo": "cm5_the_message_you_are_replying_to"
  }'

POST/v1/messages/{messageId}/react

React to a message with an emoji — the same affordance as the dashboard.

Send · 100/min Free

messageId is the 247Rep message id (from a webhook or GET /v1/messages). Send an empty emoji to remove a reaction you previously sent.

bash

# Add a reaction
curl -X POST https://api.247rep.app/v1/messages/cm5.../react \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

# Remove it
curl -X POST https://api.247rep.app/v1/messages/cm5.../react \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "" }'

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",
      "referral": null,
      "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.

Ad attribution (Click-to-WhatsApp)

json

"referral": {
  "source_type": "ad",
  "source_id": "120209...",              // Meta ad id — the ad this lead came from
  "source_url": "https://fb.me/...",
  "headline": "50% off this weekend",
  "body": "Message us to claim your code",
  "media_type": "image",
  "image_url": "https://...",
  "ctwa_clid": "ARB2...",                // click id for Meta's Conversions API
  "captured_at": "2026-06-10T08:00:00.000Z"
}

Parameters

source_id

stringoptional

The Meta ad id — use this to attribute the lead to a specific ad or campaign.

source_type

stringoptional

ad or post.

source_url

stringoptional

The ad / post link the customer tapped.

headline

stringoptional

Ad headline, when provided by Meta.

body

stringoptional

Ad body copy, when provided by Meta.

media_type

stringoptional

image or video, when the ad has media.

image_url / video_url / thumbnail_url

stringoptional

Ad creative URLs, when present.

ctwa_clid

stringoptional

Click id you can forward to Meta's Conversions API to report conversions and optimize the ad.

captured_at

stringoptional

ISO-8601 timestamp of when the referral was captured.

GET/v1/conversations/{conversationId}

Retrieve a single conversation, including automation and escalation state.

Read · 300/min

PATCH/v1/conversations/{conversationId}

Update a conversation. Set automationEnabled to pause or resume AI auto-reply on this thread.

Send · 100/min

Parameters

automationEnabled

booleanoptional

false pauses the AI on this conversation so a human can take over; true hands it back to the AI. Same toggle as the dashboard.

bash

# Pause the AI on this conversation (a human takes over)
curl -X PATCH https://api.247rep.app/v1/conversations/cm4.../ \
  -H "Authorization: Bearer rep_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "automationEnabled": false }'

# → { "success": true, "id": "cm4...", "automationEnabled": false, "status": "active" }

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 numeric Telegram chatId (e.g. 123456789) — not a phone number and not a user’s @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 · media 1 (your url) or 2/5 (uploaded)

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.

replyTo

stringoptional

Optional. Reply to an earlier message. Pass the 247Rep message id (from a webhook or GET /v1/telegram/conversations/{id}/messages) or Telegram's numeric message_id — resolved within this 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())

Reply to a message

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": "On it — shipping today!",
    "replyTo": "cm9_or_the_numeric_message_id"
  }'

POST/v1/telegram/messages/{messageId}/react

React to a Telegram message with an emoji (setMessageReaction).

Send · 100/min Free

bash

curl -X POST https://api.247rep.app/v1/telegram/messages/cm9.../react \
  -H "Authorization: Bearer rep_live_your_telegram_key" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "🔥" }'

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.

Data Connections — let the AI call your API

Six auth types are supported, secrets are encrypted at rest (AES-256-GCM), requests are SSRF-guarded and rate-limited per connection, and every call is written to a log you can inspect.

Setup steps

The New Connection wizard walks through four steps, then you add one or more endpoints.

Details — give the connection a name and description, set the base URL of your API (e.g. https://api.yourstore.com), and optionally tune the request timeout and per-minute rate limit.
Auth — choose how we authenticate to your API (see Auth types) and paste the credential. It's encrypted before it ever touches the database.
Test — we make a live call to confirm the base URL and credentials work before anything is saved.
Add endpoints — for each action the AI should be able to take, define:
- Method + path — e.g. GET /orders/{orderId}.
- Parameters — path, query, and request-body fields the AI should fill in.
- Response mapping — which fields of your response the AI should read back (so it quotes the tracking number, not the raw JSON).
- Context instructions — plain-English guidance telling the AI when and how to use this endpoint (“call this when a customer asks about an order status; ask for their order number first”).
- Contact identifier — which field identifies the customer (e.g. their phone), so the AI looks up the right person automatically.

Auth types

Pick whichever matches how your API authenticates. The credential is encrypted at rest.

Supported auth

none

—optional

Public endpoint, no credentials.

bearer

tokenoptional

Sends Authorization: Bearer <token>.

api_key_header

keyoptional

Sends your key in a custom header (you choose the header name).

api_key_query

keyoptional

Appends your key as a query-string parameter.

basic_auth

user/passoptional

HTTP Basic auth with a username and password.

oauth2_client_credentials

client id/secretoptional

We fetch and refresh an access token using the OAuth2 client-credentials grant.

custom_header

headeroptional

Any fixed custom header you specify (name + value).

Need help wiring a specific system? The Integrations page lists the pre-built ones (Shopify, Google, Zapier); anything else is a Data Connection.

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

Two ways to attach media

Parameters

Send a voice note or audio file

Response

Parameters

Reply to a message

Conversations

Parameters

Ad attribution (Click-to-WhatsApp)

Parameters

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

Reply to a message

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

Data Connections — let the AI call your API

Setup steps

Auth types

Supported auth

247RepREST API

Overview

Base URL

Test & live modes

API keys

Authorization header

Quick start

247Rep
REST API

247Rep
REST API