SOCIAL MEDIA

Chatous Poll Events API

Listen on a Chatous account's WebSocket for a bounded window and return the events that arrived: new matches with the partner's profile, incoming messages, chat disconnects and queue acknowledgements.

chatouseventsmessagesrealtime

Try it free Get an API key

How to call it

Send one POST to api.upapi.io/chatous-poll-events.get with your key in the X-Api-Key header and the parameters below as a JSON body. Each call spends 4 weighted units of your monthly quota. The operation times out after 40 seconds. Responses are not cached; every call runs the operation.

endpoint

POST https://api.upapi.io/chatous-poll-events.get

Chatous Poll Events API reference

Request parameters

proxyUrl: string — Optional proxy URL for the WebSocket. Omit to connect directly.
maxEvents: integer — Return as soon as this many socket frames have arrived.
connectSid: stringrequired — The account's connect.sid cookie value, as set on chatous.com when the account signed in.
maxSeconds: number — How long to listen before returning whatever arrived.

Response fields

events: arrayrequired
events[].age: integer | string
events[].raw: object — Present only on unknown: the frame exactly as Chatous sent it.
events[].type: stringrequired — chat = matched with a new person (carries their profile). message = a message in an existing chat. disconnect = a chat ended. queue = the server acknowledged a queue entry. unknown = a frame type this build does not recognise, with the raw payload.
events[].about: string
events[].chatId: string
events[].fromMe: boolean
events[].gender: string
events[].chat_id: string
events[].message: string
events[].queueId: string
events[].user_id: string
events[].location: string
events[].endedByMe: boolean
events[].screenname: string
events[].profile_tags: array
events[].profile_photo_icon: string
elapsedMs: integerrequired
fetchedAt: stringrequired
eventCount: integerrequired
socketOpened: booleanrequired
closedByServer: booleanrequired
unknownEventCount: integerrequired — Frames whose type this build does not recognise. A non-zero value is a shape change worth investigating, not an error.
undecodableItemCount: integerrequired — Socket items this build could not read at all - distinct from unknown events, which ARE returned with their payload. Non-zero means frames were lost to a shape change, so a zero-event answer here is not evidence the account was quiet.

Example request and response

The example response is generated from this operation’s published output schema — it shows the shape and field names, not values from a recorded call.

json — example request body

{
  "maxEvents": 50,
  "connectSid": "example",
  "maxSeconds": 15
}

json — example response shape

{
  "events": [
    {
      "age": 1,
      "raw": {},
      "type": "example",
      "about": "example",
      "chatId": "example",
      "fromMe": false,
      "gender": "example",
      "chat_id": "example",
      "message": "example",
      "queueId": "example",
      "user_id": "example",
      "location": "example",
      "endedByMe": false,
      "screenname": "example",
      "profile_tags": [
        null
      ],
      "profile_photo_icon": "example"
    }
  ],
  "elapsedMs": 1,
  "fetchedAt": "example",
  "eventCount": 1,
  "socketOpened": false,
  "closedByServer": false,
  "unknownEventCount": 1,
  "undecodableItemCount": 1
}

Code snippets

cURL

curl

curl -X POST https://api.upapi.io/chatous-poll-events.get \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{ "maxEvents": 50, "connectSid": "example", "maxSeconds": 15 }'

JavaScript

javascript

const response = await fetch('https://api.upapi.io/chatous-poll-events.get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
  "maxEvents": 50,
  "connectSid": "example",
  "maxSeconds": 15
}),
});

const data = await response.json();
console.log(data);

Python

python

import requests

response = requests.post(
    'https://api.upapi.io/chatous-poll-events.get',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
    },
    json={
  "maxEvents": 50,
  "connectSid": "example",
  "maxSeconds": 15
},
)

print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{ "maxEvents": 50, "connectSid": "example", "maxSeconds": 15 }`)

	req, _ := http.NewRequest("POST", "https://api.upapi.io/chatous-poll-events.get", bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var result map[string]any
	json.Unmarshal(body, &result)
	fmt.Println(result)
}

PHP

php

<?php

$payload = json_encode([
    'maxEvents' => 50,
    'connectSid' => 'example',
    'maxSeconds' => 15,
]);

$ch = curl_init('https://api.upapi.io/chatous-poll-events.get');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-api-key: YOUR_API_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
var_dump($data);

Ruby

ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.upapi.io/chatous-poll-events.get')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'

request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request['x-api-key'] = 'YOUR_API_KEY'
request.body = { "maxEvents": 50, "connectSid": "example", "maxSeconds": 15 }.to_json

response = http.request(request)
puts JSON.parse(response.body)

Java

java

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

OkHttpClient client = new OkHttpClient();
ObjectMapper mapper = new ObjectMapper();

String json = "{ \"maxEvents\": 50, \"connectSid\": \"example\", \"maxSeconds\": 15 }";

RequestBody body = RequestBody.create(json, MediaType.get("application/json"));
Request request = new Request.Builder()
    .url("https://api.upapi.io/chatous-poll-events.get")
    .post(body)
    .addHeader("Content-Type", "application/json")
    .addHeader("x-api-key", "YOUR_API_KEY")
    .build();

try (Response response = client.newCall(request).execute()) {
    Map<?, ?> result = mapper.readValue(response.body().string(), Map.class);
    System.out.println(result);
}

csharp

using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = JsonSerializer.Deserialize<object>("{ \"maxEvents\": 50, \"connectSid\": \"example\", \"maxSeconds\": 15 }");
var response = await client.PostAsJsonAsync("https://api.upapi.io/chatous-poll-events.get", payload);

var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);

Frequently asked questions

How much does the Chatous Poll Events API cost per call?

Each call spends 4 weighted units of your plan's monthly quota. Full pricing is at https://upapi.io/pricing.

How do I authenticate to the Chatous Poll Events API?

Send your key in the X-Api-Key header. A free guest key is available without creating an account.

Are Chatous Poll Events API responses cached?

No — every call runs the operation live; responses are not cached.

More Social Media APIs

Chatous Get Account State Chatous Check Session Wellfound Conversation Detail Wellfound List Conversations Check Reddit Account Health Check Reddit Comment Visibility Get Bluesky Profile Get Contra Company Profile

Browse every Social Media API →