Skip to content

AddContact#

Beta version

The functionality is in beta. Features may change and may work unstably.

Test Postman Apidog

The method is intended for adding a number to contacts.

How Telegram contacts differ from the phone book of the main device

Telegram has its own contact manager, which is not linked to the phone book of the main device. This is done to improve privacy, as well as for the convenience of transferring Telegram contacts when working on different devices: Android, iOS, Windows, WEB.

Request#

To add a number to contacts, you need to send a request to:

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

To obtain the apiUrl, idInstance and apiTokenInstance request parameters, refer to the Before you start section.

Request parameters#

Parameter Type Required Description
chatId string Yes User's сhatId in the personal chat identifier format. For example, "10000000"
firstName string Yes Contact's first name
lastName string No Contact's last name

Request body example#

{
    "chatId": "10000000",
    "firstName": "Ivan",
    "lastName": "Tsarevich"
},
{
    "chatId": "79876543210@c.us",
    "firstName": "Ivan",
    "lastName": "Tsarevich"
}

Response#

Response fields#

Field Type Description
addContact boolean Returns True if the method was executed without errors. Absent in the response body with an error
messsage string Error description if the method was executed with an error. Absent in the response body without an error

Response body example#

{
    "addContact": true
}

Method execution with an error#

status code 400 Bad request

{
    "message": "Contact 10000000 already exists"
}

status code 404 Not found

{
    "message": "10000000 is not on Telegram"
}

AddContact errors#

For the list of errors common to all methods, see the Standard errors section.

HTTP code Error identifier Description
400 Bad Request
Contact 10000000 already exists		 A contact with this number already exists in the phone book
404 Not found
10000000 is not on Telegram		 A contact with this number is not on Telegram

Code examples#

import requests

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

payload = {
    "chatId": "10000000",
    "firstName": "Ivan",
    "lastName": "Tsarevich"
}
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' => '10000000',
    'firstName' => 'Ivan',
    'lastName' => 'Tsarevich'
);

$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": "10000000",
    "firstName": "Ivan",
    "lastName": "Tsarevich"
}'

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"":""10000000"",""firstName"":""Ivan"", ""lastName"":""Tsarevich""}"

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": "10000000", "firstName": "Ivan", "lastName": "Tsarevich"}', 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.