Skip to content

AddContact#

Test Postman Apidog

The method is used for adding a number to contacts, as well as adding a number to the primary device's (handset's) phonebook.

What's the difference between WhatsApp contacts and the primary device's phonebook?

WhatsApp has its own contact manager, which is not linked to the primary device's phonebook by default. This is done to enhance privacy and to make it easier to transfer WhatsApp contacts across different devices: Android, iOS, Windows, and the web. By default, contact synchronization between the primary device's phonebook and WhatsApp may be disabled, so you need to enable contact synchronization in the API and, sometimes, on your primary device. For more information, see the article How to manage the contact list in the phone book of a connected phone?

Request#

To add a number to your contacts, , you need to execute a request at:

POST 
{{apiUrl}}/waInstance{{idInstance}}/addContact/{{apiTokenInstance}}

For apiUrl, idInstance and apiTokenInstance request parameters, refer to Before you start section.

Request parameters#

Parameter Type Mandatory Description
chatId string Yes Phone number in the format of a personal chat ID. For example "79876543210@c.us"
firstName string Yes Contact first name
lastName string No Contact last name
saveInAddressbook boolean No Flag to save the contact into the primary device's phonebook. Default value is true.

Request body example#

{
    "chatId": "79876543210@c.us",
    "firstName": "John",
    "lastName": "Doe",
    "saveInAddressbook": true 
}

Response#

Response parameters#

Parameter Type Description
addContact boolean The method returns true if all is completed without errors. Not present in the error response body.
messsage string Error description if the method failed. Not present in a successful response body.

Response body example#

{
    "addContact": true
}

Method execution with error#

status code 400 Bad request 

{
    "message": "Contact 77059640505@c.us already exists"
}

status code 404 Not found 

{
    "message": "77059640505@c.us is not on WhatsApp"
}

AddContact errors#

For a list of errors common to all methods, refer to Common errors section

HTTP code Error identifier Description
400 Bad Request
Contact 79876543210@c.us already exists		 The contact with this number is already in your phone book
404 Not found
79876543210@c.us is not on WhatsApp		 The contact with this number does not exist in WhatsApp

Request examples#

import requests

url = "{{apiUrl}}/waInstance{{idInstance}}/addContact/{{apiTokenInstance}}"

payload = {
    "chatId": "79876543210@c.us",
    "firstName": "John",
    "lastName": "Doe",
    "saveInAddressbook": true
}
headers = {
'Content-Type': 'application/json'
}

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

print(response.text.encode('utf8'))

<?php
//The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
$url = '{{apiUrl}}/waInstance{{idInstance}}/addContact/{{apiTokenInstance}}';

//chatId is the number (@c.us)  
$data = array(
    'chatId' => '71234567890@c.us',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'saveInAddressbook' => 'true',
);

$options = array(
    'http' => array(
        'header' => "Content-Type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($data)
    )
);

$context = stream_context_create($options);

$response = file_get_contents($url, false, $context);

echo $response;
?>

curl --location '{{apiUrl}}/waInstance{{idInstance}}/addContact/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId": "71234567890@c.us",
    "firstName": "John",
    "lastName": "Doe",
    "saveInAddressbook": true
}'

Sub AddContact()
Dim URL As String
Dim RequestBody As String
Dim http As Object

' The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
URL = "{{apiUrl}}/waInstance{{idInstance}}/addContact/{{apiTokenInstance}}"

' chatId is the number (@c.us)
RequestBody = "{""chatId"":""71234567890@c.us"",""firstName"":""John"", ""lastName"":""Doe"", ""saveInAddressbook"":""true""}"

Set http = CreateObject("MSXML2.XMLHTTP")

With http
    .Open "POST", URL, False
    .setRequestHeader "Content-Type", "application/json"
    .send RequestBody
End With

Set http = Nothing

End Sub

program addContact;

{$APPTYPE CONSOLE}

uses
System.SysUtils,
System.Classes, System.Net.HttpClient, System.Net.URLClient, System.Net.HttpClientComponent;

var
HttpClient: TNetHTTPClient;
RequestBody: TStringStream;
RequestHeaders: TNetHeaders;
Response: IHTTPResponse;
EndpointURL, ID_INSTANCE, API_TOKEN_INSTANCE: string;

begin
ID_INSTANCE := '110100001';
API_TOKEN_INSTANCE := 'd75b3a66374942c5b3c019c698abc2067e151558acbd451234';

EndpointURL := 'https://api.green-api.com/waInstance' + ID_INSTANCE + '/addContact/' + API_TOKEN_INSTANCE;

HttpClient := TNetHTTPClient.Create(nil);
RequestBody := TStringStream.Create('{ "chatId": "79876543210@c.us", "firstName": "John", "lastName": "Doe", "saveInAddressbook": true }', TEncoding.UTF8);
RequestHeaders := [
    TNetHeader.Create('Content-Type', 'application/json')
];

try
    Response := HTTPClient.Post(EndpointURL, RequestBody, nil, RequestHeaders);

    if Response.StatusCode = 200 then
    Writeln('[Response]: ' + Response.ContentAsString)
    else
    Writeln('[ERROR ' + IntToStr(Response.StatusCode) + ']:' + Response.StatusText + '' + Response.ContentAsString);

    readln;
except
    on E: Exception do
    Writeln(E.ClassName, ': ', E.Message);
end;

HttpClient.Free;
RequestBody.Free;

end.