Quick Start

Get up and running with the Berlay API in minutes.

Overview

Berlay provides two integration styles:

  • Custom Webhooks — push events from any app into Berlay using a per-channel API key
  • REST API v1 — read and write conversations, messages, contacts, and ratings programmatically

Base URL: https://api.berlay.app

Authentication

Custom webhook API key

Obtained from Admin → Integrations → Custom / API → Connect. Pass it as a header:

http
POST /api/webhooks/custom/{channelId}
Content-Type: application/json
x-berlay-api-key: brly_your_api_key_here

REST API Bearer token

Created in your organization API settings. Include it on every request:

http
Authorization: Bearer brly_sk_your_key_here
Keys are shown in full only once at creation time. Only a SHA-256 hash is stored. If you lose a key, revoke it and generate a new one.

First request

Step 1 — Create a Custom / API integration in Admin → Integrations → Custom / API → Connect

Step 2 — Copy your API key (shown once) and inbound webhook URL from the connect screen.

Step 3 — Send a test event:

http
POST https://api.berlay.app/api/webhooks/custom/123
Content-Type: application/json
x-berlay-api-key: brly_your_api_key_here

{
  "messageId": "msg_001",
  "conversationId": "session_abc",
  "from": {
    "externalId": "user_42",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "subject": "Help with my order",
  "content": "Hi, I placed an order but haven't received a confirmation."
}

The conversation appears in your inbox within seconds. The endpoint always returns 200 OK — check the channel event log for delivery status.

Rate limits

EndpointLimit
POST /api/auth/magic-link5 requests / minute per IP
All other endpoints60 requests / second per IP

Exceeding the limit returns 429 Too Many Requests.

Next steps