PATCH /project/{project_id}/contact/{id} — Update Contact

Use this endpoint to update one or more fields on an existing contact. You can change their display name, manage their opt-in or blocked status, and set or update custom attributes.

This is a partial update (PATCH semantics). Only the fields you include in the request body will be modified. Any fields you omit remain unchanged. You do not need to send the full contact object.

Endpoint

PATCH https://connect.api-wa.co/project-apis/v1/project/{project_id}/contact/{contact_id}

Authentication

Include your project API password in every request header:

X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD

Path Parameters

string

required

Your Convo project ID. You can find this in your Convo dashboard under Project Settings.

string

required

The Convo contact ID of the contact to update (e.g., 64f3a1e0c8e4d500123abc00). You can obtain this from the Create Contact or Get Contact responses.

Request Body

string

Updated display name for the contact. Replaces the existing name.

boolean

Set to false to opt this contact out of WhatsApp notifications. Set to true to re-opt them in.

boolean

Set to true to block this contact. Blocked contacts cannot receive any messages. Set to false to unblock them.

object

Key-value pairs of custom attributes to set or update on the contact. This is a merge operation — new keys are added, and existing keys are updated. Keys not present in the request are left unchanged.Example:

{
  "plan": "premium",
  "city": "Mumbai",
  "signup_date": "2024-01-15"
}

Examples

Update Attributes
Opt Out Contact
Full Update

Update a contact’s name and set custom attributes:

curl -X PATCH \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "name": "Priya Sharma",
    "attributes": {
      "plan": "premium",
      "city": "Mumbai",
      "signup_date": "2024-01-15"
    }
  }'

Opt a contact out of WhatsApp notifications:

curl -X PATCH \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "opted_in": false
  }'

Update multiple fields in a single request:

curl -X PATCH \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "name": "Priya Sharma",
    "opted_in": false,
    "blocked": false,
    "attributes": {
      "plan": "premium",
      "city": "Mumbai",
      "signup_date": "2024-01-15"
    }
  }'

Opting out a contact is significant. Once opted_in is set to false, you cannot send proactive messages (template/HSM messages) to that contact until they opt back in. Only inbound-initiated session messages can be exchanged within an active 24-hour conversation window. Make sure you have the contact’s consent before modifying this field.

Response

200 OK — Returns the full updated contact object.

{
  "id": "64f3a1e0c8e4d500123abc00",
  "project_id": "YOUR_PROJECT_ID",
  "phone_number": "917089379345",
  "name": "Priya Sharma",
  "country_code": "91",
  "on_whatsapp": true,
  "is_closed": false,
  "is_intervened": false,
  "is_requesting": false,
  "last_active": 1710050000000,
  "tags": ["vip", "newsletter"],
  "attributes": {
    "plan": "premium",
    "city": "Mumbai",
    "signup_date": "2024-01-15"
  },
  "first_message": {
    "id": "msg_001",
    "added_at": 1710000500000
  },
  "created_at": 1710000000000
}

string

The Convo contact ID.

string

The Convo project this contact belongs to.

string

The contact’s WhatsApp phone number (with country code, no +).

string

The contact’s updated display name.

string

The numeric country dialing code (e.g., "91" for India).

boolean

true if the phone number is active on WhatsApp.

boolean

true if the conversation with this contact is marked as closed.

boolean

true if a human agent is handling this contact’s conversation.

boolean

true if the contact has an active pending request awaiting a human agent response.

number

Unix timestamp in milliseconds of the contact’s most recent activity.

array

Current list of tags applied to this contact.

object

The contact’s full custom attributes map after the merge update.

object

Object containing id and added_at for the contact’s first inbound message.

number

Unix timestamp in milliseconds when this contact was originally created.

Error Responses

HTTP Status	Meaning
`400`	Bad request — invalid field value or request body format.
`401`	Unauthorized — invalid or missing `X-API-WA-Project-API-Pwd` header.
`404`	Contact not found — the `contact_id` does not exist in this project.

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

PATCH /project/{project_id}/contact/{id} — Update Contact

Endpoint

Authentication

Path Parameters

Request Body

Examples

Response

Error Responses

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Examples

​Response

​Error Responses

Endpoint

Authentication

Path Parameters

Request Body

Examples

Response

Error Responses