Protocol Documentation

Master the Relay Uplink. Integrate professional-grade notifications into your technology stack in seconds.

Situation Automation

Trigger notifications based on real-world events. Use categories to route messages automatically.

Universal Catchall

Point any webhook to our catchall endpoint. We parse your JSON automatically.

Global Branding

Set your bot name and avatar globally or override per request in your code.

Integration SDK v26.4

CONFIGURATOR

curl implementation
curl -X POST https://relay-notify.com/api/relay \
  -H "x-api-key: RELAY_PK_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "target": "@chat_id",
    "message": "Situation: {{situation}} detected in {{location}}",
    "category": "Security / Alarm",
    "botName": "Aether Sentinel",
    "variables": {
  "situation": "Fire Alarm",
  "location": "Warehouse A"
}
  }'
javascript implementation
// Modern Fetch API
const relay = async () => {
  const response = await fetch('https://relay-notify.com/api/relay', {
    method: 'POST',
    headers: { 'x-api-key': 'RELAY_PK_XXXX', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      platform: 'telegram',
      target: '@chat_id',
      message: `Situation: {{situation}} detected in {{location}}`,
      category: 'Situation-Trigger',
      variables: {
  "situation": "Fire Alarm",
  "location": "Warehouse A"
}
    })
  });
  const data = await response.json();
  console.log(data);
};
python implementation
import requests

url = "https://relay-notify.com/api/relay"
payload = {
    "platform": "telegram",
    "target": "@chat_id",
    "message": "Situation: {{situation}} detected in {{location}}",
    "category": "Automation",
    "variables": {
  "situation": "Fire Alarm",
  "location": "Warehouse A"
}
}
headers = {"x-api-key": "RELAY_PK_XXXX", "Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
php implementation
<?php

$url = "https://relay-notify.com/api/relay";
$payload = json_encode([
    "platform" => "telegram",
    "target" => "@chat_id",
    "message" => "Situation: {{situation}} detected in {{location}}",
    "category" => "Billing",
    "variables" => {
  "situation"=> "Fire Alarm",
  "location"=> "Warehouse A"
}
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json", "x-api-key: RELAY_PK_XXXX"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
go implementation
package main
import ("bytes"; "net/http")
func main() {
	url := "https://relay-notify.com/api/relay"
	json := []byte(`{"platform":"telegram","target":"@chat_id","message":"Situation: {{situation}} detected in {{location}}"}`)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(json))
	req.Header.Set("x-api-key", "RELAY_PK_XXXX")
	http.DefaultClient.Do(req)
}

Target Addressing Guide

The syntax for your target parameter shifts depending on the selected destination. To guarantee successful delivery, format your targets exactly as dictated below.

Telegram

Literal numerical Chat ID or mapped Username Alias.

1780002457 OR @MyChannel

Slack

Member ID or public Channel ID routing hash.

U0AQHJA77QB OR C12345ABCDE

Discord

Zero-auth webhook URL. Sourced from Server Integrations.

https://discord.com/api/webhooks/123/xyz...

Email

Standard globally routed electronic mail address.

director@relay-notify.com

WhatsApp

Full international format without '+' or leading zeros.

34612345678

WhatsApp Setup Protocol

To relay messages via WhatsApp, you must integrate with the official Meta Business API. Follow these steps to obtain your active credentials:

  • 01
    Create Developer App

    Go to developers.facebook.com and create a 'Business' type application.

  • 02
    Verify Number

    Connect your SIM number for verification. It cannot be active on a regular WhatsApp app simultaneously.

  • 03
    Get Phone ID

    Copy the 'Phone Number ID' from the WhatsApp > Getting Started panel.

  • 04
    Permanent Token

    Generate a System User token with 'whatsapp_business_messaging' permissions.

Target Format

"target": "34612345678" // Format: CC + Area + Number

PRO-TIP:WhatsApp requires pre-approved templates in Meta Suite. Ensure your templateId matches exactly and variables match the template schema.

Response Protocols

SUCCESS (HTTP 200)

{
  "status": "success",
  "messageId": "rl_81a2x98...",
  "deliveredTo": ["telegram"],
  "timestamp": "2024-04-07T13:42:01Z"
}

ERROR (HTTP 4XX/5XX)

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "Protocol identity not verified."
}

Status Code Reference

CodeScenarioResolution
401_UNAUTHORIZEDMissing or invalid x-api-key.Check Dashboard Registry.
402_PAYMENT_REQUIREDMonthly transmission quota exceeded.Upgrade Tier in Pricing.
400_INVALID_TARGETTarget ID format mismatch for platform.Review Addressing Guide.
503_PROVIDER_DOWNDownstream provider (e.g. Meta) technical fail.Relay will queue for retry.