POST Chat

Execute a chat command

Publish a normal chat message or execute a configured command.

POST /api/v3/{appid}/chat/rooms/{roomid}/command

Publish a normal chat message or execute a configured command.

Send plain text in command for an ordinary message. The user identified by userid must join the room first. A successful response includes the published speech event, which will also arrive through the room updates stream.

Request

Parameters

Values in the path and query string.

appid path

string TalkLabs ID required

The TalkLabs application ID assigned to your account.

Example: your-app-id

roomid path

string TalkLabs ID required

The TalkLabs assigned room ID returned when the room was created.

Example: room-id

Request

JSON body

Send as application/json.

command

string required

The message or command to publish. Plain text sends a normal chat message; reserved prefixes can invoke configured action or administrator commands.

userid

string customer-defined required

The customer defined ID of the user sending the command.

eventtype

string

Optional event type override for structured application events.

customtype

string

A customer defined event type. Use with eventtype custom.

customid

string customer-defined

A customer defined ID for the new event.

custompayload

string

Customer defined structured data, commonly serialized JSON.

Request example

{
  "command": "<chat_exec_hello_world>",
  "userid": "u-8842"
}

Request examples

Common variations

Historical examples filtered through the current request schema.

Execute Chat Command (say 'Hello, World!')

{
  "command": "<chat_exec_hello_world>",
  "userid": "u-8842"
}

Execute Chat Command (Announcement by Admin)

{
  "command": "*announce This is an announcement by the Admin.",
  "userid": "u-8842"
}

Execute Chat Command (profanity test)

{
  "command": "No, you're misunderstaning me, Prince Valiant. I'm saying if you were a sheep, would you fuck a sheep, if you were another sheep? We can't tolerate that in Scunthorpe.",
  "userid": "u-8842",
  "customtype": "",
  "customid": "",
  "custompayload": ""
}

Execute Action Command

{
  "command": "/high5 georgew",
  "userid": "u-8842",
  "customtype": "",
  "customid": "",
  "custompayload": ""
}

Execute Admin Command (*help)

{
  "command": "*help",
  "userid": "u-8842",
  "customtype": "",
  "customid": "",
  "custompayload": ""
}

Delete All Events in Room

{
  "command": "*deleteallevents",
  "userid": "u-8842"
}

Response

Status codes

Every JSON response uses the API result envelope.

200 OK ApiResult

400 Bad Request ApiResult

403 Forbidden ApiResult

409 Conflict ApiResult

412 Precondition Failed — the user must join the room first. ApiResult

418 Too many messages were sent in a short interval. ApiResult

Example response · 200

{
  "message": "",
  "errors": {},
  "data": {
    "kind": "chat.executecommand",
    "op": "speech",
    "room": {
      "kind": "chat.room",
      "id": "5ec2047286c2921ad07edd39",
      "appid": "5ec2038a86c2921ad07edd35",
      "ownerid": "u-8842",
      "name": "New York City Chat (Post-Moderated)",
      "description": "Live from the top of the Empire State Building",
      "customtype": "",
      "customid": "5th-stand",
      "custompayload": "",
      "customtags": [],
      "customfield1": "",
      "customfield2": "",
      "enableactions": true,
      "enableenterandexit": true,
      "open": true,
      "inroom": 1,
      "added": "2020-05-18T03:43:46.3198116Z",
      "whenmodified": "2020-05-18T03:43:46.3198116Z",
      "moderation": "post",
      "maxreports": 0,
      "enableprofanityfilter": true,
      "delaymessageseconds": 0
    },
    "speech": {
      "kind": "chat.event",
      "id": "5ec204d986c2921ad07edd3d",
      "roomid": "5ec2047286c2921ad07edd39",
      "body": "Hello, SportsTalk247.com World!↵",
      "added": "2020-05-18T03:45:29.3561662Z",
      "ts": 637253703293561600,
      "eventtype": "speech",
      "userid": "userid_abe",
      "user": {
        "kind": "app.user",
        "userid": "userid_abe",
        "handle": "HonestAbe",
        "handlelowercase": "honestabe",
        "displayname": "Abraham Lincoln",
        "pictureurl": "https://www.biography.com/.image/ar_1:1%2Cc_fill%2Ccs_srgb%2Cg_face%2Cq_auto:good%2Cw_300/MTU5MDUzMTE0Mzk2MTI0OTUy/abraham-lincoln-1809---18652c-sixteenth-president-of-the-united-states-of-america-photo-by-stock-montagestock-montagegetty-images_promo.jpg",
        "profileurl": "https://www.biography.com/us-president/abraham-lincoln",
        "banned": false
      },
      "customtype": "",
      "customid": null,
      "custompayload": "",
      "customtags": [],
      "customfield1": "",
      "customfield2": "",
      "replyto": null,
      "parentid": "",
      "hierarchy": [],
      "edited": false,
      "deleted": false,
      "active": true,
      "mutedby": [],
      "shadowban": false,
      "hashtags": [],
      "likecount": 0,
      "replycount": 0,
      "reactions": [],
      "moderation": "na",
      "reports": []
    },
    "action": null
  }
}

curl --request POST \
  --url "https://api.sportstalk247.com/api/v3/${APP_ID}/chat/rooms/${ROOM_ID}/command" \
  --header "Accept: application/json" \
  --header "x-api-token: ${TALKLABS_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "command": "<chat_exec_hello_world>",
  "userid": "u-8842"
}'

const appId = process.env.TALKLABS_APP_ID;
const roomid = 'room-id';

const response = await fetch(
  `https://api.sportstalk247.com/api/v3/${appId}/chat/rooms/${roomid}/command`,
{
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'x-api-token': process.env.TALKLABS_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "command": "<chat_exec_hello_world>",
  "userid": "u-8842"
}),
});

const result = await response.json();

import json
import os
import requests

app_id = os.environ["TALKLABS_APP_ID"]
roomid = "room-id"

response = requests.post(
    f"https://api.sportstalk247.com/api/v3/{app_id}/chat/rooms/{roomid}/command",
    headers={
        "Accept": "application/json",
        "x-api-token": os.environ["TALKLABS_API_TOKEN"],
    },
    json=json.loads(r'''{
  "command": "<chat_exec_hello_world>",
  "userid": "u-8842"
}'''),
)
response.raise_for_status()
result = response.json()

Environment variables TALKLABS_APP_ID TALKLABS_API_TOKEN

Response