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"
}
'import requests
url = "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert"
payload = {
"chat_id": "[email protected]",
"first_name": "John",
"last_name": "Doe"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({chat_id: '[email protected]', first_name: 'John', last_name: 'Doe'})
};
fetch('https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chat_id' => '[email protected]',
'first_name' => 'John',
'last_name' => 'Doe'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert"
payload := strings.NewReader("{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}"
response = http.request(request)
puts response.read_body{
"message": "Contact upserted successfully.",
"data": {
"success": true
}
}{
"message": "Resource not found."
}{
"message": "The given data was invalid.",
"errors": {},
"statusCode": 422
}{
"message": "Internal Server Error"
}Upsert Contact
Update or create a contact in your phone address book and WhatsApp.
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"
}
'import requests
url = "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert"
payload = {
"chat_id": "[email protected]",
"first_name": "John",
"last_name": "Doe"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({chat_id: '[email protected]', first_name: 'John', last_name: 'Doe'})
};
fetch('https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chat_id' => '[email protected]',
'first_name' => 'John',
'last_name' => 'Doe'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert"
payload := strings.NewReader("{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chat_id\": \"[email protected]\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n}"
response = http.request(request)
puts response.read_body{
"message": "Contact upserted successfully.",
"data": {
"success": true
}
}{
"message": "Resource not found."
}{
"message": "The given data was invalid.",
"errors": {},
"statusCode": 422
}{
"message": "Internal Server Error"
}Update a contact in your phone address book using a phone number.
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 using the contact’s phone number
This endpoint is intended for phone-number-based contact management and address book synchronization.
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
Use the contact’s phone number only.- Phone number:
12132132130
Send the number with country code and without spaces or the
+ sign. Example: 12132132130Do not use an
@lid identifier with this endpoint.If the same person is handled once by phone number and again by LID, WhatsApp may treat them as two separate contacts. For upsert operations, always use the phone number only.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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
application/json
Example:
"application/json"
application/json
Example:
"application/json"
Path Parameters
Instance UUID copied from hypersender dashboard
Example:
"{{ instance_id }}"
Body
application/json
Phone number (123123123) or chat ID ([email protected] or 123123@lid)
Example:
The contact's first name
Example:
"John"
The contact's last name
Example:
"Doe"