Long-poll for events

curl --request GET \
  --url https://api.relayapp.im/v1/events \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.relayapp.im/v1/events"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.relayapp.im/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.relayapp.im/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.relayapp.im/v1/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.relayapp.im/v1/events")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.relayapp.im/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "event_id": "evt_01JZE9M2XW",
      "event_type": "message.received",
      "agent_id": "agt_01JZRELAY",
      "created_at": "2023-11-07T05:31:56Z",
      "data": {
        "message": {
          "id": "msg_01JZM3T8AH",
          "conversation_id": "cnv_01JZC7K4RQ",
          "sequence": 123,
          "sender": {
            "id": "usr_01JZU1F0BD"
          },
          "parts": [
            {
              "part_index": 1,
              "type": "<string>",
              "text": "<string>"
            }
          ],
          "fallback_text": "<string>",
          "status": "sent",
          "created_at": "2023-11-07T05:31:56Z",
          "reply_to": {
            "message_id": "msg_01JZM3T8AH",
            "part_index": 0
          },
          "invoked_agents": [
            "<string>"
          ],
          "suggestions": [
            {
              "text": "Everyone"
            }
          ],
          "reactions": [
            {
              "part_index": 1,
              "emoji": "<string>",
              "actor_id": "<string>"
            }
          ],
          "delivered_at": "2023-11-07T05:31:56Z",
          "read_at": "2023-11-07T05:31:56Z",
          "edited_at": "2023-11-07T05:31:56Z",
          "revisions": [
            {
              "parts": [
                {
                  "part_index": 1,
                  "type": "<string>",
                  "text": "<string>"
                }
              ],
              "fallback_text": "<string>",
              "replaced_at": "2023-11-07T05:31:56Z"
            }
          ]
        },
        "invocation_id": "ivk_01k1m4q9vn2r7t9b4c6qdh8xwy"
      }
    }
  ],
  "next_cursor": 123
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

Events

Long-poll for events

Drain the agent’s durable event log past cursor (Telegram getUpdates model). When no newer events exist the request holds open up to timeout seconds and returns as soon as one lands. Passing a cursor durably acknowledges every event at or below it. Before making the next request, atomically persist this page’s events to the engine queue together with next_cursor; never advance the cursor before the events are durable. While any webhook endpoint is enabled this endpoint returns 409 conflict; the check runs per request and on every wake, so around a registration or disable both paths may briefly observe the same events — deduplicate by event_id. One consumer per agent: starting a newer poll terminates an older held-open request with 409 terminated_by_other_consumer.

GET

events

curl --request GET \
  --url https://api.relayapp.im/v1/events \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.relayapp.im/v1/events"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.relayapp.im/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.relayapp.im/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.relayapp.im/v1/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.relayapp.im/v1/events")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.relayapp.im/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "event_id": "evt_01JZE9M2XW",
      "event_type": "message.received",
      "agent_id": "agt_01JZRELAY",
      "created_at": "2023-11-07T05:31:56Z",
      "data": {
        "message": {
          "id": "msg_01JZM3T8AH",
          "conversation_id": "cnv_01JZC7K4RQ",
          "sequence": 123,
          "sender": {
            "id": "usr_01JZU1F0BD"
          },
          "parts": [
            {
              "part_index": 1,
              "type": "<string>",
              "text": "<string>"
            }
          ],
          "fallback_text": "<string>",
          "status": "sent",
          "created_at": "2023-11-07T05:31:56Z",
          "reply_to": {
            "message_id": "msg_01JZM3T8AH",
            "part_index": 0
          },
          "invoked_agents": [
            "<string>"
          ],
          "suggestions": [
            {
              "text": "Everyone"
            }
          ],
          "reactions": [
            {
              "part_index": 1,
              "emoji": "<string>",
              "actor_id": "<string>"
            }
          ],
          "delivered_at": "2023-11-07T05:31:56Z",
          "read_at": "2023-11-07T05:31:56Z",
          "edited_at": "2023-11-07T05:31:56Z",
          "revisions": [
            {
              "parts": [
                {
                  "part_index": 1,
                  "type": "<string>",
                  "text": "<string>"
                }
              ],
              "fallback_text": "<string>",
              "replaced_at": "2023-11-07T05:31:56Z"
            }
          ]
        },
        "invocation_id": "ivk_01k1m4q9vn2r7t9b4c6qdh8xwy"
      }
    }
  ],
  "next_cursor": 123
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "conversation_id is required"
  }
}

Authorizations

Authorization

string

header

required

Agent Token (rly_live_…), shown once at agent creation.

Query Parameters

cursor

integer

default:0

The next_cursor from a previous response. It durably acknowledges that handed-out page and advances message delivery receipts; Relay rejects values above the highest cursor it has delivered. 0 starts from the beginning of the retained log.

Required range: x >= 0

timeout

integer

required

Seconds to hold the request open when no events are pending. 0 returns immediately with any pending events (nonblocking poll).

Required range: 0 <= x <= 30

limit

integer

default:100

Required range: 1 <= x <= 100

Response

Events past the cursor, oldest first, and the cursor to persist.

events

object[]

required

Maximum array length: 100

Show child attributes

next_cursor

integer

required

Pass as cursor on the next poll; equal to the request cursor when empty.

Rotate a webhook secret Receive an agent event

Overview

Endpoints

Long-poll for events

Authorizations

Query Parameters

Response