import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
});
async function main() {
const response = await client.phones.createPhone();
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/phones/create' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"phone_id": "phone-aaaaaaaaaaaa",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"phone_name": "Support",
"phone_image": "https://example.com/files/image.png",
"wa_state": "CONNECTED",
"is_ready": true,
"qr_code": null,
"label_ids": {
"label-aaaaaaaaaaaa": true
},
"labels": [
"support",
"priority"
],
"is_browser_open": true,
"last_disconnect": null,
"queue_status": null,
"first_connected_at": "2026-01-15T09:30:00.000Z",
"created_at": "2026-01-10T12:00:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Create Phone
Creates a new phone in the workspace and boots its instance. Do not send an x-phone header.
import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
});
async function main() {
const response = await client.phones.createPhone();
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/phones/create' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"phone_id": "phone-aaaaaaaaaaaa",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"phone_name": "Support",
"phone_image": "https://example.com/files/image.png",
"wa_state": "CONNECTED",
"is_ready": true,
"qr_code": null,
"label_ids": {
"label-aaaaaaaaaaaa": true
},
"labels": [
"support",
"priority"
],
"is_browser_open": true,
"last_disconnect": null,
"queue_status": null,
"first_connected_at": "2026-01-15T09:30:00.000Z",
"created_at": "2026-01-10T12:00:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.
Response
The newly created phone. org_phone and wa_state stay null until a WhatsApp account is connected via the QR.
A phone — a slot in the workspace that a WhatsApp account connects to by scanning a QR code. All phone-scoped endpoints act through one phone, selected with the x-phone header (org phone number or phone_id).
Unique id of the phone (phone-xxxxxxxxxxxxxxxx). Accepted as the x-phone header value on phone-scoped endpoints.
"phone-aaaaaaaaaaaa"
Id of the organization the phone belongs to
"00000000-0000-0000-0000-000000000000"
WhatsApp number connected to the phone, as country code + number suffixed with @c.us. null until a WhatsApp account has been connected by scanning the QR.
"911111111111@c.us"
Display name of the phone
"Support"
URL of the profile image of the phone
"https://example.com/files/image.png"
WhatsApp connection state — 'CONNECTED' when the session is live, 'UNPAIRED'/'UNPAIRED_IDLE' while awaiting a QR scan, other transient states include 'OPENING', 'PAIRING', 'TIMEOUT' and 'CONFLICT'. null before the phone has ever connected.
"CONNECTED"
Whether the phone instance is booted and ready to send and receive messages
true
Raw QR payload while the phone is awaiting a QR scan; null once connected. Use GET /phones/qr to render it as a scannable image.
Labels assigned to the phone, keyed by label_id (true = assigned)
Show child attributes
Show child attributes
{ "label-aaaaaaaaaaaa": true }
Names of the labels assigned to the phone, resolved from label_ids
["support", "priority"]
Whether the phone's WhatsApp Web browser session is currently open
true
Details of the most recent disconnect event, if any. null when the phone has never disconnected.
Status of the phone's outgoing message queue, if any messages are queued
When a WhatsApp account was first connected to the phone, as an ISO 8601 timestamp. null if never connected.
"2026-01-15T09:30:00.000Z"
When the phone was created, as an ISO 8601 timestamp
"2026-01-10T12:00:00.000Z"
When the phone was last updated, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
Was this page helpful?