Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
<?php
declare(strict_types=1);
namespace OpenWA\Resources;
use OpenWA\Http\HttpExecutor;
/**
* Contacts resource — contact lookup and management.
*
* Backed by src/modules/contact/contact.controller.ts.
*/
class ContactsResource
{
private HttpExecutor $http;
public function __construct(HttpExecutor $http)
{
$this->http = $http;
}
/**
* @param array<string,mixed> $query
* @return array<int,array<string,mixed>>
*/
public function list(string $sessionId, array $query = []): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts", $query) ?? [];
}
/** @return array<string,mixed> */
public function get(string $sessionId, string $contactId): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}");
}
/**
* Check whether a number is on WhatsApp. Requires an OPERATOR key.
*
* @return array<string,mixed>
*/
public function check(string $sessionId, string $number): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/check/{$this->http->encodeSegment($number)}");
}
/** @return array<string,mixed> */
public function profilePicture(string $sessionId, string $contactId): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}/profile-picture");
}
/**
* Batch-resolve profile picture URLs for up to 50 contacts in one request.
*
* @param list<string> $ids
* @return array{pictures: array<string,?string>} Map of contact id → URL (null when a lookup fails). An id skipped after a lookup timed out is absent from the map; ask for it again.
*/
public function profilePictures(string $sessionId, array $ids): array
{
return $this->http->request(
'GET',
"/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/profile-pictures",
['ids' => implode(',', $ids)]
);
}
/** @return array<string,mixed> */
public function phone(string $sessionId, string $contactId): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}/phone");
}
/**
* Block a contact. Requires an OPERATOR key.
*
* @return array<string,mixed>
*/
public function block(string $sessionId, string $contactId): array
{
return $this->http->request('POST', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}/block");
}
/**
* Save a contact to the addressbook, or edit an existing entry. Requires an OPERATOR key.
*
* @param array<string,mixed> $body firstName and an optional lastName.
* @return array<string,mixed>
*/
public function upsert(string $sessionId, string $contactId, array $body): array
{
return $this->http->request('PUT', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}", [], $body) ?? [];
}
/**
* Remove a contact from the addressbook. Requires an OPERATOR key.
*
* @return array<string,mixed>
*/
public function delete(string $sessionId, string $contactId): array
{
return $this->http->request('DELETE', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}") ?? [];
}
/**
* Unblock a contact. Requires an OPERATOR key.
*
* @return array<string,mixed>
*/
public function unblock(string $sessionId, string $contactId): array
{
return $this->http->request('DELETE', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/{$this->http->encodeSegment($contactId)}/block");
}
/**
* List the JIDs this account has blocked.
*
* Session-wide, so it takes no contact id — unlike block() and unblock(), which act on one
* contact. Returns a bare list of ids, not contact records.
*
* @return array<int,string>
*/
public function listBlocked(string $sessionId): array
{
return $this->http->request('GET', "/api/sessions/{$this->http->encodeSegment($sessionId)}/contacts/blocked");
}
}