> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Update phone > Updates the display name, profile image and/or labels of the phone. Name and image changes are pushed to WhatsApp. ## OpenAPI ````yaml api-reference/openapi-generated.json PATCH /v1/phones/update openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/phones/update: patch: tags: - Phones summary: Update a phone description: >- Updates the display name, profile image and/or labels of the phone. Name and image changes are pushed to WhatsApp. operationId: updatePhone parameters: - schema: type: string minLength: 1 example: '919876543210' description: >- Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). The phone must be connected to the org and accessible by the API token. required: true description: >- Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). The phone must be connected to the org and accessible by the API token. name: x-phone in: header requestBody: content: application/json: schema: type: object properties: phone_name: type: string description: >- New display name for the phone, updated on WhatsApp. Phones running the WhatsApp Business App cannot be renamed. example: Support phone_image: type: string format: uri description: >- Public URL of the new profile image for the phone, updated on WhatsApp example: https://example.com/images/support.png labels: type: string nullable: true description: >- Comma-separated label names to assign to the phone, e.g. 'support,priority'. Case-insensitive. Labels that do not exist yet are created. Replaces the phone's existing labels as a whole — pass the full desired list, not just additions. Pass null or an empty string to remove every label from the phone. example: support,priority responses: '200': description: The updated phone content: application/json: schema: $ref: '#/components/schemas/Phone' examples: default: summary: Response body value: 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' '400': description: The phone server is disconnected or not reachable content: application/json: examples: error: summary: The phone server is disconnected or not reachable value: code: ERROR message: The phone server is disconnected or not reachable status: 400 schema: type: object properties: code: type: string example: ERROR message: type: string example: The phone server is disconnected or not reachable status: type: integer example: 400 example: code: ERROR message: The phone server is disconnected or not reachable status: 400 '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: '919876543210', // the phone to act with (x-phone) }); async function main() { const response = await client.phones.updatePhone({ phone_name: 'Support', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X PATCH 'https://api.periskope.app/v1/phones/update' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' \ -H 'Content-Type: application/json' \ -d '{ "phone_name": "Support" }' components: schemas: Phone: type: object properties: phone_id: type: string description: >- Unique id of the phone (phone-xxxxxxxxxxxxxxxx). Accepted as the x-phone header value on phone-scoped endpoints. example: phone-aaaaaaaaaaaa org_id: type: string format: uuid description: Id of the organization the phone belongs to example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- 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. example: 911111111111@c.us phone_name: type: string description: Display name of the phone example: Support phone_image: type: string description: URL of the profile image of the phone example: https://example.com/files/image.png wa_state: type: string description: >- 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. example: CONNECTED is_ready: type: boolean description: >- Whether the phone instance is booted and ready to send and receive messages example: true qr_code: type: string description: >- 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. label_ids: type: object additionalProperties: type: boolean description: Labels assigned to the phone, keyed by label_id (true = assigned) example: label-aaaaaaaaaaaa: true labels: type: array items: type: string description: Names of the labels assigned to the phone, resolved from label_ids example: - support - priority is_browser_open: type: boolean description: Whether the phone's WhatsApp Web browser session is currently open example: true last_disconnect: description: >- Details of the most recent disconnect event, if any. null when the phone has never disconnected. queue_status: description: >- Status of the phone's outgoing message queue, if any messages are queued first_connected_at: type: string description: >- When a WhatsApp account was first connected to the phone, as an ISO 8601 timestamp. null if never connected. example: '2026-01-15T09:30:00.000Z' created_at: type: string description: When the phone was created, as an ISO 8601 timestamp example: '2026-01-10T12:00:00.000Z' updated_at: type: string description: When the phone was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' description: >- 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). securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.