Users API

Retrieve and browse your chatbot's users programmatically through the Developer API.

---

Base URL

https://api.peki.ai/api

Authentication

All endpoints require HMAC-SHA256 authentication. See the Messages API guide for full details on signature generation.

Required Headers

Header	Required	Description
Content-Type	✅	Must be application/json
X-API-Key	✅	Your API key (starts with pk_)
X-Signature	✅	HMAC-SHA256 signature
X-Timestamp	✅	Unix timestamp in seconds

---

List Users

Get all users for your chatbot with pagination.

GET /Dev/{chatbotId}/users

Path Parameters

Parameter	Type	Required	Description
chatbotId	string	✅	The unique identifier for your chatbot

Query Parameters

Parameter	Type	Required	Default	Description
page	int	❌	1	Page number (1-based)
pageSize	int	❌	20	Number of items per page

Response

{
  "data": [
    {
      "id": "6612a1b2c3d4e5f6a7b8c9d0",
      "chatbotId": "your_chatbot_id",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phoneNumber": "+1234567890",
      "username": "johndoe",
      "source": "Dev",
      "dataDictionary": {
        "city": "Istanbul"
      },
      "messageTimestamp": "2025-04-08T12:00:00Z",
      "lastReceivedText": "Hello!",
      "createdAt": "2025-04-01T10:00:00Z",
      "updatedAt": "2025-04-08T12:00:00Z"
    }
  ],
  "error": null,
  "totalItems": 45,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 3
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the user
chatbotId	string	The chatbot this user belongs to
firstName	string	User's first name
lastName	string	User's last name
email	string	User's email address
phoneNumber	string	User's phone number
username	string	User's username
source	string	Platform where the user originated (Web, Dev, etc.)
dataDictionary	object	Custom key-value data attached to the user
messageTimestamp	datetime	Timestamp of the user's last message
lastReceivedText	string	The most recent message sent by the user
createdAt	datetime	When the user profile was created
updatedAt	datetime	When the user profile was last updated

---

Get User

Get a single user by their ID.

GET /Dev/{chatbotId}/users/{userId}

Path Parameters

Parameter	Type	Required	Description
chatbotId	string	✅	The unique identifier for your chatbot
userId	string	✅	The unique identifier for the user

Response

{
  "data": {
    "id": "6612a1b2c3d4e5f6a7b8c9d0",
    "chatbotId": "your_chatbot_id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+1234567890",
    "username": "johndoe",
    "source": "Dev",
    "createdAt": "2025-04-01T10:00:00Z",
    "updatedAt": "2025-04-08T12:00:00Z"
  },
  "error": null
}

Error Response

{
  "data": null,
  "error": "User not found."
}

---

Pagination

All list endpoints return paginated results with the following metadata:

Field	Type	Description
totalItems	int	Total number of records
pageSize	int	Number of items per page
currentPage	int	Current page number
totalPages	int	Total number of pages

Use the page and pageSize query parameters to navigate through results. Results are ordered by creation date (newest first).

---

Code Examples

JavaScript

const crypto = require("crypto");

const apiKey = "pk_your_api_key";
const apiSecret = "sk_your_api_secret";
const chatbotId = "your_chatbot_id";

const timestamp = Math.floor(Date.now() / 1000);
const path = `/api/Dev/${chatbotId}/users?page=1&pageSize=20`;
const payload = `GET\n${path}\n\n${timestamp}`;
const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(payload)
  .digest("base64");

const response = await fetch(`https://api.peki.ai${path}`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
    "X-Signature": signature,
    "X-Timestamp": timestamp.toString(),
  },
});

const result = await response.json();
console.log("Users:", result.data);
console.log("Total:", result.totalItems);

Python

import hmac, hashlib, base64, time, requests

api_key = 'pk_your_api_key'
api_secret = 'sk_your_api_secret'
chatbot_id = 'your_chatbot_id'

timestamp = str(int(time.time()))
path = f'/api/Dev/{chatbot_id}/users?page=1&pageSize=20'
payload = f'GET\n{path}\n\n{timestamp}'

signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key,
    'X-Signature': signature,
    'X-Timestamp': timestamp
}

response = requests.get(f'https://api.peki.ai{path}', headers=headers)
result = response.json()
print('Users:', result['data'])
print('Total:', result['totalItems'])

cURL

API_KEY="pk_your_api_key"
API_SECRET="sk_your_api_secret"
CHATBOT_ID="your_chatbot_id"

TIMESTAMP=$(date +%s)
REQ_PATH="/api/Dev/$CHATBOT_ID/users?page=1&pageSize=20"
PAYLOAD="GET\n$REQ_PATH\n\n$TIMESTAMP"
SIGNATURE=$(echo -ne "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -s "https://api.peki.ai$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"

---

Error Codes

Status Code	Description
401	Invalid API key or signature
403	API key doesn't have access to the specified chatbot
404	User not found
500	Internal server error