Chat API
Approved integrations only
This API is available only for Poki-approved chat integrations.
1. Request chat messages
Use the following endpoint to request potential chat messages.
No Authorization header is required.
Game ID placeholder
Replace 00000000-0000-0000-0000-000000000000 with your own Poki game ID in all examples on this page.
Request body
{
"game_id": "00000000-0000-0000-0000-000000000000",
"input": "hi",
"num": 5,
"usernames": ["Bob", "Alice"],
"chat_id": "123123",
"user_id": "456456"
}
Request fields
| Field | Required | Description |
|---|---|---|
game_id |
Yes | Your Poki game ID. Replace the example value with your own game ID. |
input |
Yes | The text typed by the user. |
chat_id |
Yes | A unique identifier for the chat. This can be a string in any format. |
user_id |
Yes | A unique identifier for the user. This can be a string in any format. |
num |
No | The number of messages to return. Defaults to 1, maximum 10. |
usernames |
No | An array of usernames of people in the chat. |
The usernames parameter supports mentioning specific users by name using @username in the input text. In our database of messages we have [username] placeholders that will then be replaced by the specific username from the input. We will do a fuzzy match on the usernames provided here, so a user could type @bob and if the usernames array contains Bobby, we would replace [username] with @Bobby in the returned messages.
Example request
const body = {
game_id: '00000000-0000-0000-0000-000000000000', // Replace with your own game ID.
input: 'hi',
num: 5,
usernames: ['Bob', 'Alice'],
chat_id: '123123',
user_id: '456456',
};
fetch('https://dialog.poki.io/v2/chat', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Example response
{
"messages": [
{
"english": "Hi",
"spanish": "Hola",
"tagged_english": "Hi",
"tagged_spanish": "Hola",
"score": 1,
"signature": "C_tjr_OlHZEGmT0e2fsnoLEh5QW2Smv4Ap4NfrjMSgboHIj0v2FXKGt4mCmLQRKOJCKVXfCaP2yRFUUoMjjhDQ"
},
{
"english": "Hi 👋",
"spanish": "Hola 👋",
"tagged_english": "Hi 👋",
"tagged_spanish": "Hola 👋",
"score": 0.926,
"signature": "WQAHmwk5V0DM7n5wDgkiojNcge8WW6C8ik1RsCba13JtX_JtKvIdJ8As-IxgyFnZkBKSRYenTtFwivVP11ORBg"
},
{
"english": "Hi ❤️",
"spanish": "Hola ❤️",
"tagged_english": "Hi ❤️",
"tagged_spanish": "Hola ❤️",
"score": 0.924,
"signature": "tb97LVmp_xqv2Uqu6DL6tF4KDMPd0SrdXK0KJL17cOlZS_5cuNeP0Zgq5q_AI0dOlGBFMa5CHSzuk-gM5244BA"
},
{
"english": "Hiiii",
"spanish": "Holaaaa",
"tagged_english": "Hiiii",
"tagged_spanish": "Holaaaa",
"score": 0.838,
"signature": "c7BNeQ_Yz7U1km3D3Bk_qkhrndk4Jyo6-fmeMMOjj_lSA8NsH0Fb9YVKjEzpzqOvgvJ5IIGoLxMMNh6X0xlpAA"
},
{
"english": "Hey",
"spanish": "Oye",
"tagged_english": "Hey",
"tagged_spanish": "Oye",
"score": 0.759,
"signature": "AsjUkYK7mUyk3QCrKWuzydCbsMATRjmKLB2rMnW-kIhNhKk587QIC2HF9z-lgPkRqjkm0vJ5LvY994UpF-LTCg"
}
]
}
Response fields
| Field | Description |
|---|---|
english |
The English chat message. |
spanish |
The Spanish chat message. |
tagged_english |
The English chat message with tags applied. |
tagged_spanish |
The Spanish chat message with tags applied. |
score |
A relevance score for the returned message. |
signature |
A signature that can be used to verify that the message was generated by the Chat API. |
If the request returns a non-2xx response, treat it as if no suggestions are available and fall back to your normal chat behavior.
2. Verify signed messages
The signature field can be used to verify that a message was generated by the Chat API. This makes it safe to send the message a user picked over something like Netlib and validate it on the receiving side before showing it.
This signature can be validated client side using the following code:
const b64uDec = s => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
async function importPubRaw(b64u) {
return crypto.subtle.importKey('raw', b64uDec(b64u), 'Ed25519', false, ['verify']);
}
async function verify(message, publicKeys) {
const values = [
message.english,
message.spanish,
message.tagged_english,
message.tagged_spanish,
message.score.toString(),
];
const data = new TextEncoder().encode((`msg:v1:${values.filter(Boolean).join('|')}`).normalize('NFKC'));
const sig = b64uDec(message.signature);
for (const publicKey of publicKeys) {
const key = await importPubRaw(publicKey);
if (await crypto.subtle.verify('Ed25519', key, sig, data)) {
return true;
}
}
return false;
}
const isValid = await verify(
results[0],
[
// Array of public keys so Poki can publish new keys in the future, without breaking existing signatures.
'ufhdvvj76lPxGTeIP0OP0gdvu-nn0dPBGd5P7Hhq_HQ',
],
);
3. Log sent messages
When the user sends one of the returned messages, you must log it with the following endpoint.
No Authorization header is required.
Request body
{
"game_id": "00000000-0000-0000-0000-000000000000",
"input": "what was typed",
"num": 2,
"message": "the message that was sent in either English or Spanish",
"chat_id": "123123",
"user_id": "456456"
}
This is the same payload as the chat request, with an additional message field containing the message that was picked.
Example request
const body = {
game_id: '00000000-0000-0000-0000-000000000000', // Replace with your own game ID.
input: 'what was typed',
num: 2,
message: 'the message that was sent in either English or Spanish',
chat_id: '123123',
user_id: '456456',
};
fetch('https://dialog.poki.io/v2/log', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
})
.then(response => {
if (!response.ok) {
throw new Error(`Failed to log chat message: ${response.status}`);
}
})
.catch(error => console.log('error', error));
4. Full integration example
This example shows how the Chat API can be wired into a chat input. The config fields are used for the /v2/chat and /v2/log payloads. Typing in the chatbox requests suggestions after a short delay, and clicking a suggestion posts it in the example chat and logs the selected message.
Replace the example game ID with your own Poki game ID before trying this integration.