Rename a contact

PATCHhttps://api.wapito.com/v1/contacts/{id}

Send a channel token on every request: Authorization: Bearer wpt_YOUR_TOKEN

Beta

Last reviewed September 17, 2026

Writes a name into the address book of the linked phone so the contact shows up with a useful label in WhatsApp itself and in every chat list this channel exposes. Only the NOWEB engine can write contacts, so GOWS channels receive `engine_unsupported_feature` with a hint to switch. It changes nothing on the contact side.

Not on every engine. A channel runs on one of two protocol engines, gows (the default) or noweb, and this call is not implemented on both. On the engine that lacks it the API answers 501 engine_unsupported_feature with a hint naming the engine that has it.

Parameters

Name	In	Type	Required	Description	Example
`id`	path	`string`	Required	Contact id, in any accepted recipient form.	`+15551234567`

Request body

Fields of the request body
Field	Type	Required	Description
`first_name`	`string`	Optional	Given name.
`last_name`	`string`	Optional	Family name.
`name`	`string`	Optional	Full display name; used when the engine does not split names.

{
  "first_name": "Dana",
  "last_name": "Whitfield"
}

Responses

200

The contact after the change.

Fields of the 200 response
Field	Type	Required	Description
`id`	`string`	Required	Contact id in `@s.whatsapp.net` form.
`is_blocked`	`boolean`	Required	Whether the channel has blocked this contact.
`is_business`	`boolean`	Required	Whether the account is a WhatsApp Business account.
`is_me`	`boolean`	Required	Whether this contact is the channel itself.
`lid`	`string \| null`	Required	Linked device identifier (LID) when WhatsApp exposes one for this contact.
`name`	`string \| null`	Required	Name from the linked phone address book.
`phone`	`string \| null`	Required	Phone number in digits, without `+`.
`picture`	`string \| null`	Required	Profile picture URL.
`push_name`	`string \| null`	Required	Name the contact publishes to others.
`short_name`	`string \| null`	Required	Shortened display name.

{
  "id": "15551234567@s.whatsapp.net",
  "is_blocked": false,
  "is_business": false,
  "is_me": false,
  "lid": "187264518273645@lid",
  "name": "Dana Whitfield",
  "phone": "15551234567",
  "picture": "https://pps.whatsapp.net/v/t61.24694-24/example_n.jpg",
  "push_name": "Dana",
  "short_name": "Dana"
}

400

The request body or query string is malformed, or the recipient cannot be parsed into a WhatsApp id.

Show 2 example bodies

invalid_recipient — `to` is not a dialable number or valid WhatsApp id

{
  "error": {
    "code": "invalid_recipient",
    "details": {
      "to": "+1555"
    },
    "message": "The recipient is not a valid WhatsApp address.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

invalid_request — schema validation failed

{
  "error": {
    "code": "invalid_request",
    "details": {
      "issues": [
        {
          "message": "Array must contain at least 2 element(s)",
          "path": "body.options"
        }
      ]
    },
    "message": "The request payload failed validation.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

401

The channel token is missing, malformed, revoked or belongs to a deleted channel.

Show 2 example bodies

token_revoked — the token was rotated in the dashboard

{
  "error": {
    "code": "token_revoked",
    "message": "This channel token has been revoked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

unauthorized — no or unusable Bearer token

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid channel token.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

403

The token is valid but the channel may not perform this action right now.

Show 2 example bodies

channel_locked — billing lapsed or the channel was locked by an operator

{
  "error": {
    "code": "channel_locked",
    "details": {
      "reason": "plan_required"
    },
    "message": "This channel is locked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

forbidden — the channel does not own the target object

{
  "error": {
    "code": "forbidden",
    "message": "You are not allowed to perform this action.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

404

The addressed object does not exist, or the number is not on WhatsApp.

Show 3 example bodies

message_not_found — the message id is unknown to the engine

{
  "error": {
    "code": "message_not_found",
    "message": "The requested message does not exist.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

not_found — unknown id

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

not_on_whatsapp — the number is not registered

{
  "error": {
    "code": "not_on_whatsapp",
    "message": "This number is not registered on WhatsApp.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

409

The channel is in the wrong state for this action, or the account type does not support it.

Show 3 example bodies

business_account_required — labels need WhatsApp Business

{
  "error": {
    "code": "business_account_required",
    "message": "This action requires a WhatsApp Business account.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_connected — link the number first

{
  "error": {
    "code": "channel_not_connected",
    "details": {
      "status": "qr"
    },
    "message": "The channel is not connected.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_in_qr_state — no QR available while the session boots

{
  "error": {
    "code": "channel_not_in_qr_state",
    "details": {
      "status": "created"
    },
    "message": "The channel is not waiting for a QR scan.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

429

A rate limit, a plan quota or one of the anti-ban guards stopped the request. Every one of these is safe to retry later; read `Retry-After` when present.

Show 5 example bodies

cold_send_limit — too many first messages to new recipients this hour

{
  "error": {
    "code": "cold_send_limit",
    "details": {
      "resets_at": "2026-09-15T09:00:00.000Z",
      "window_cap": 20
    },
    "message": "The hourly limit for messages to new recipients is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

quota_exceeded — plan quota for the day or month

{
  "error": {
    "code": "quota_exceeded",
    "details": {
      "quota": "sent",
      "resets_at": "2026-09-16T00:00:00.000Z",
      "used": 150
    },
    "message": "The plan quota for this resource is exhausted.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

rate_limited — per-minute API rate limit

{
  "error": {
    "code": "rate_limited",
    "details": {
      "retry_after": 12
    },
    "message": "Too many requests.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

send_rate_limited — the send queue did not drain within 20 s

{
  "error": {
    "code": "send_rate_limited",
    "details": {
      "retry_after": 5
    },
    "message": "The send queue for this channel is saturated.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

warmup_limit — the warm-up ladder cap for today

{
  "error": {
    "code": "warmup_limit",
    "details": {
      "cap": 200,
      "day": 2
    },
    "message": "The warm-up limit for this channel is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

500

Something went wrong inside Wapito. Quote `request_id` when reporting it.

Show the example body

internal_error — unexpected failure

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

501

The feature is not available. `engine_unsupported_feature` means the other engine can do it and `details.hint` tells you how to switch; `feature_not_available` means no engine supports it yet.

Show 2 example bodies

engine_unsupported_feature — supported on the other engine

{
  "error": {
    "code": "engine_unsupported_feature",
    "details": {
      "hint": "Switch this channel to the noweb engine in the dashboard.",
      "supported_engines": [
        "noweb"
      ]
    },
    "message": "The engine of this channel does not support that feature.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

feature_not_available — phase 2, no engine support

{
  "error": {
    "code": "feature_not_available",
    "details": {
      "phase": 2
    },
    "message": "This feature is not available.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

502

The engine answered with an error Wapito could not translate into a more specific code.

Show the example body

engine_error — unexpected engine failure

{
  "error": {
    "code": "engine_error",
    "details": {
      "engine": "gows",
      "status": 500
    },
    "message": "The WhatsApp engine returned an error.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

503

The engine session is not reachable. Retry with backoff.

Show the example body

engine_unavailable — engine down or restarting

{
  "error": {
    "code": "engine_unavailable",
    "details": {
      "engine": "gows"
    },
    "message": "The WhatsApp engine is unavailable.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

504

The engine did not answer before the upstream timeout.

Show the example body

engine_timeout — no answer within the deadline

{
  "error": {
    "code": "engine_timeout",
    "details": {
      "timeout_ms": 20000
    },
    "message": "The WhatsApp engine did not respond in time.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

Webhook events

contactsContact discovered or resolvedonContacts()

Errors

Code examples

import requests

url = "https://api.wapito.com/v1/contacts/+15551234567"

payload = {
    "first_name": "Dana",
    "last_name": "Whitfield"
}
headers = {
    "Authorization": "Bearer wpt_YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())

Other endpoints in this group

Reference

Try it on your own number

Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.

Create a free channel Read the docs

Parameters

Request body

Responses

200

400

401

403

404

409

429

500

501

502

503

504

Webhook events

Errors

Code examples

Related

Other endpoints in this group

Reference

Try it on your own number