Upsert Contact - Hypersender

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"
}

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: 12132132130

Do 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

Authorization

string

header

required

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

Headers

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

Show child attributes

Get Profile Picture Get All Known LIDs

​Use Cases

​Contact Management

​CRM Synchronization

​Bulk Contact Import

​Request Parameters

​chat_id

​first_name

​last_name

​Response Examples

​Successful Response

​Best Practices

​Multiple Requests

​Verification

​Error Handling

Authorizations

Headers

Path Parameters

Body

Response

Use Cases

Contact Management

CRM Synchronization

Bulk Contact Import

Request Parameters

chat_id

first_name

last_name

Response Examples

Successful Response

Best Practices

Multiple Requests

Verification

Error Handling