Skip to main content
POST
/
{instance}
/
contacts
/
upsert
Upsert contact
curl --request POST \
  --url https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chat_id": "[email protected]",
  "first_name": "John",
  "last_name": "Doe"
}
'
{
  "message": "Contact upserted successfully.",
  "data": {
    "success": true
  }
}
Update contact on your phone address book (and in WhatsApp). This endpoint allows you to:
  • Create a new contact in your phone’s address book
  • Update an existing contact’s information
  • Sync contact details to WhatsApp
This is useful for managing your WhatsApp contacts programmatically and keeping your address book synchronized.

​
Use Cases

​
Contact Management

Automatically create or update contacts when new users register in your system.

​
CRM Synchronization

Keep your WhatsApp contacts in sync with your CRM database.

​
Bulk Contact Import

Import and update multiple contacts from external sources.

​
Request Parameters

​
chat_id

The contact identifier can be in one of these formats:
  • Phone number: 12132132130
  • Chat ID (regular): [email protected]
  • Chat ID (lid): 1234567890@lid
- chat ID can end with “@c.us” or “@lid”, or can be just a phone number - 12132132130

​
first_name

The contact’s first name (required).

​
last_name

The contact’s last name (optional).

​
Response Examples

​
Successful Response

When the contact is upserted successfully: 
{
  "message": "Contact upserted successfully.",
  "data": {
    "success": true
  }
}
Phone Address Book Update NoteIf you have multiple WhatsApp apps installed on your phone, the API might only work with one account. You may need to make a few API requests with the same parameters and wait a few seconds between requests to update your phone address book.

​
Best Practices

​
Multiple Requests

If the contact doesn’t appear in your address book immediately, try making 2-3 requests with a few seconds delay between them.

​
Verification

After upserting a contact, you can use the Get Contact endpoint to verify the update was successful.

​
Error Handling

Always implement proper error handling to catch validation errors or API failures.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Accept
string

application/json

Example:

"application/json"

​
Content-Type
string

application/json

Example:

"application/json"

Path Parameters

​
instance
string
required

Instance UUID copied from hypersender dashboard

Example:

"{{ instance_id }}"

Body

application/json
​
chat_id
string
required

Phone number (123123123) or chat ID ([email protected] or 123123@lid)

Example:

"[email protected]"

​
first_name
string
required

The contact's first name

Example:

"John"

​
last_name
string

The contact's last name

Example:

"Doe"

Response

Contact upserted successfully

​
message
string
Example:

"Contact upserted successfully."

​
data
object