Introduction

Welcome to the Pact API! You can use our API as a single messaging API. You can view code examples in the dark area to the right.

This API was designed by way Implement only required. Feel you free to contact with support if you are sure what make sense to append additional methods.

5 easy steps for integration:

1. Signup here
2. Get your API token in account settings
3. Connect WhatsApp or Instagram or anything here
4. Setup webhooks using this doc
5. Try to send or receive message

Options for using our service

1. Curl

You could use curl or others tools for interact with our service

2. SDK-PHP

You could use our SDK-PHP

Private API V1

Authentication

All requests to Pact API must be authenticated.

There are two options for autentication:

Pact expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-Private-Api-Token: YOUR_API_TOKEN

or as a additional parameter in URI

"API_ENDPOINT_HERE?private_api_token=YOUR_API_TOKEN"

You can get your Pact API key from account settings page.

Examples

# Header
curl -X GET "API_ENDPOINT_HERE"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

# OR use a private_api_token parameter
curl -X GET "API_ENDPOINT_HERE?private_api_token=YOUR_API_TOKEN"

<?php
$token = '<your super secret token>';
$pact = new \Pact\PactClient($token);

Companies

Get All Companies

curl "https://api.pact.im/p1/companies"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * This method return list of all user companies
 * @link https://pact-im.github.io/api-doc/#companies
 *
 * @param string $from Next page token geted from last request.
 *               Not valid or empty token return first page
 * @param int $per Number of elements per page. Default: 50
 * @param string $sort Change sorting direction. Available values: asc, desc. Default: asc.
 * @return Json|null
 */

// Get companies without params

$client->companies->getCompanies();

// Get companies with params

$client->companies->getCompanies($from, $per, $sort)

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "companies":[
         {
            "external_id":1,
            "name":"COMPANY_NAME",
            "phone":null,
            "description":null,
            "webhook_url":null
         }
      ],
      "next_page": "fslkfg2lkdfmlwkmlmw4of94wg34lfkm34lg"
   }
}

This endpoint return list of all user companies.

HTTP Request

GET https://api.pact.im/p1/companies

Query Parameters

Update company

curl -X PUT "https://api.pact.im/p1/companies/ID"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "name=Test"

<?php

/**
  * This method updates specific company attributes
  * @link https://pact-im.github.io/api-doc/#get-all-companies
  *
  * @param int $companyId Id of the company for update
  * @param string $name Company name
  * @param string $phone Official company phone number of contact person
  * @param string $description Company description
  * @param string $webhook_url Endpoint for webhooks
  * @return Json|null
  */

$client->companies->updateCompany($companyId,
                                  $name,
                                  $phone,
                                  $description,
                                  $webhook_url);

The above command returns JSON structured like this:

{
   "status":"updated",
   "data":{
      "external_id":2
   }
}

This endpoint updates specific company attributes.

HTTP Request

PUT https://api.pact.im/p1/companies/<ID>

URL Parameters

Query Parameters

Create new company

curl -X POST "https://api.pact.im/p1/companies"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "name=Test"

<?php

/**
 * This method creates a new company for user
 * @link https://pact-im.github.io/api-doc/#update-company
 *
 * @param string $name Company name
 * @param string $phone Official company phone number of contact person
 * @param string $description Company description
 * @param string $webhook_url Endpoint for webhooks
 * @return Json|null
 */

$client->companies->createCompany($name,
                                  $phone,
                                  $description,
                                  $webhook_url);

The above command returns JSON structured like this:

{
   "status":"created",
   "data":{
      "external_id":2
   }
}

This endpoint creates a new company for user.

HTTP Request

POST https://api.pact.im/p1/companies

Query Parameters

Channels

In order to receive and send messages, you need to connect channels. Channels is a source of incoming messages in the system. Channel providers:

• WhatsApp
• Instagram_business
• Telegram
• Telegram Personal
• Viber
• VK
• Facebook

You can also connect required channels via our web interface under the settings page.

Get All channels

curl "https://api.pact.im/p1/companies/COMPANY_ID/channels"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * This method returns all the company channels.
 * @link https://pact-im.github.io/api-doc/#get-all-channels
 *
 * @param int $companyId Id of the company
 * @param string $from Next page token geted from last request. Not valid or empty token return first page
 * @param int $per Number of elements per page. Default: 50
 * @param string $sort Change sorting direction (sorting by id). Avilable values: asc, desc. Default: asc.
 */

$client->channels->getChannels($companyId,
                               $from,
                               $per,
                               $sort);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "channels":[
         {
            "external_id":399,
            "provider":"whatsapp"
         }
      ],
      "next_page": "fslkfg2lkdfmlwkmlmw4of94wg34lfkm34lg"
   }
}

This endpoint returns all the company channels.

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/channels

Query Parameters

URL Parameters

Create new channel

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=telegram&token=12345677890"

Create channel:

<?php

/**
 * Unified method that can create channel in company.
 * @link https://pact-im.github.io/api-doc/#create-new-channel
 * @note You can connect only one channel per one company for each provider.
 *       Contact with support if you want to use more than one channel
 *
 * @param int $companyId Id of the company
 * @param string $provider
 * @param array $parameters
 */

// # Create channel unified method
// Note: The array of parameters variables depending on the provider
//       You need add required parameters for your particular provider

$parameters = [
  'sync_messages_from' => $syncMessagesFrom
  // ...
];

$client->channels->createChannelUnified($companyId,
                                        $provider,
                                        $parameters);

Create whatsapp channel:

<?php

/**
 * This method create a new channel for WhatsApp
 * @link https://pact-im.github.io/api-doc/#create-new-channel
 *
 * @param int $companyId Id of the company
 * @param DateTimeInterface $syncMessagesFrom Only messages created after will be synchronized
 * @param bool $doNotMarkAsRead Do not mark chats as read after synchronization
 * @return Json|null
 */

$client->channels->createChannelWhatsApp(
  $companyId,
  $syncMessagesFrom,
  $doNotMarkAsRead,
  $phone
);

Create instagram business channel:

<?php

/**
 * This method create a new channel for InstagramBusiness
 * @link https://pact-im.github.io/api-doc/#create-new-channel
 *
 * @param int $companyId Id of the company
 * @param string $private_api_token on our side
 * @param string $provider there must be "instagram_business"
 * @param hash $data data from Instagram
 * @param string $token from Instagram data hash
 * @param string $phone user phone
 * @return Json|null
 */

$client->channels->createChannelInstagramBusiness(
  $companyId,
  $private_api_token,
  $provider,
  $data,
  $token
  $phone
);

Create facebook/vkontakte/vkontakte_direct/telegram/viber channel

<?php

/**
 * This method create a new channel in the company using token.
 * @link https://pact-im.github.io/api-doc/#create-new-channel
 * @note List of supported channels that can be created by token
 *       you can see in link above
 *
 * @param int $companyId Id of the company
 * @param string $provider (facebook, viber, vk, ...)
 * @param string $token
 * @return Json|null
 */

$client->channels->createChannelByToken(
  $companyId,
  $provider,
  $token
);

The above command returns JSON structured like this:

{
   "status": "created",
   "data": {
      "external_id": 1
   }
}

This endpoint create a new channel in the company.

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels

URL Parameters

Query Parameters

Create whatsapp channel

Create whatsapp business channel (dialog360 by token)

Create whatsapp business channel (dialog360 by channel_id)

Create avito channel

Create instagram business channel

Steps:

1. It is necessary to follow the instructions for Facebook until you receive the token.

2. Make a request for https://graph.facebook.com/v4.0/me?fields=first_name,last_name,picture,name,email indicating the token.
   In the response you will receive information about your user.

3. Send a request to us p1/companies/<company_id>/channels.
   The request body must contain:
   • provider: “instagram_business”
   • token: “token”
   • phone: “+79131112233”
   • data: “response body to previous request”

   At this stage, a channel was created and information on Instagram business accounts was uploaded.

4. Send a request to p1/companies/<company_id>/channels/<external_id>/enable_page_instagram?page_id=<page[:id]>&sync_period=<sync_period>.

   external_id - parameter from previous request
   page[:id] - parameter from previous request
   sync_period - used to determine what period of messages will be synchronized: day, week, month, all.

   This is necessary in order to determine which Instagram account to use.

Create facebook/vkontakte/vkontakte_direct/telegram/viber channel

Create telegram personal channel (by qr code)

Create telegram personal channel (by digital code)

Request code Confirm code

Get token for vk group:

1. Open “Manage” in selected group
2. Open “API usage” (https://vk.com/public?act=tokens)
3. Create and copy new token

Update channel

curl -X PUT "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "token=9876543210"

Update channel:

<?php

/**
 * This method updates existing channel in the company
 * @link https://pact-im.github.io/api-doc/#update-channel
 *
 * @param int $companyId
 * @param int $conversationId
 * @param array $parameters
 * @return Json|null
 */

// # Update channel unified method
// Note: The array of parameters variables depending on the provider
//       You need add required parameters for your particular provider

$parameters = [
  'login' => $login,
  'password' => $password,
  // ...
];

$client->channels->updateChannel(
  $companyId,
  $conversationId,
  $parameters
);

Update instagram channel:

<?php

/**
 * This method updates instagramm channel
 * @link https://pact-im.github.io/api-doc/#update-channel
 *
 * @param int $companyId
 * @param int $conversationId
 * @param string $login Instagram login
 * @param string $password Instagram password
 * @return Json|null
 */

$client->channels->updateChannelInstagram(
  $companyId,
  $conversationId,
  $login,
  $password
);

Update facebook/vkontakte/vkontakte_direct/telegram/viber channel:

<?php

/**
 * This method updates channels that using tokens to auth
 * @link https://pact-im.github.io/api-doc/#update-channel
 * @note List of supported channels that can be created by token
 *       you can see in link above
 *
 * @param int $companyId
 * @param int $conversationId
 * @param string $token
 * @return Json|null
 */

$client->channels->updateChannelToken(
  $companyId,
  $conversationId,
  $token
);

The above command returns JSON structured like this:

{
   "status":"updated",
   "data":{
      "external_id":2
   }
}

This endpoint updates existing channel in the company.

HTTP Request

PUT https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>

URL Parameters

Query Parameters

For facebook/vkontakte/vkontakte_direct/telegram/viber/instagram_business channels

Delete channel

curl -X DELETE "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

Delete channel:

<?php
/**
 * Method deletes (disables) the channel
 * @link https://pact-im.github.io/api-doc/#delete-channel
 *
 * @param int $companyId Id of the company
 * @param int $channelId Id of the conversation
 */

$client->chanells->deleteChannel($companyId, $channelId);

The above command returns JSON structured like this:

{
   "status":"deleted"
}

HTTP Request

DELETE https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>

URL Parameters

How to write first message to Whatsapp

Send first message to whatsapp

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/conversations"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "phone=79250000001&text=message"

<?php

/**
 * Send first message to whatsapp
 * @link https://pact-im.github.io/api-doc/#how-to-write-first-message-to-whatsapp
 *
 * @param int $companyId Id of the company
 * @param int $channelId Id of the conversation
 * @param string $phone Phone number
 * @param string $message Message text
 */

$client->channels->sendFirstWhatsAppMessage(
  $companyId,
  $channelId,
  $phone,
  $message
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "id":17,
      "company_id":154,
      "channel":{
         "id":399,
         "type":"whatsapp"
      },
      "state":"trying_deliver",
      "conversation_id":null,
      "message_id":null,
      "details":null,
      "created_at":1510393147
   }
}

How to check if user has Whatsapp account

curl -X GET "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/user_exists?phone=79250000001"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

The above command returns JSON structured like this:

{
   "status":"ok",
   "exists": true
}

How to write first message to Whatsapp Business

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/conversations"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "phone=79250000001&template[id]=template_id&template[language_code]=ru&template[parameters][]=имя"

<?php

/**
 * Send first message to whatsapp business
 * @link https://pact-im.github.io/api-doc/#how-to-write-first-message-to-whatsapp
 *
 * @param int $companyId Id of the company
 * @param int $channelId Id of the conversation
 * @param string $phone Phone number
 * @param string $message Message text
 */

$template = [
  'id' => $templateId,
  'language_code' => $templateLanguageCode,
  'parameters' => []
];

$client->channels->sendFirstWhatsAppMessage(
  $companyId,
  $channelId,
  $phone,
  $template
);

This endpoint provides an ability to create conversation with a client in whatsapp channel. When you execute this request we will add a job for delivery. We will send webhook when the operation is complete or failed.

You can also poll delivery status here: Jobs

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/conversations

URL Parameters

Query Parameters

Whatsapp Business Template Parameters

Request code (whatsapp)

Request code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/request_code"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=whatsapp"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#request-code-whatsapp
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'provider' => 'whatsapp'
];

$client->channels->requestChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
   "sessionId": "1426",
   "code": "ZHHJ-KQSP",
   "ttl": "160s"
}

In the WhatsApp mobile application, you will receive a notification asking you to insert an authorization code. Enter the value “code” there

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/request_code

URL Parameters

Query Parameters

Request challenge code

Request code (telegram personal)

Request code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/request_code"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=telegram_personal"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#request-code-telegram-personal
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'provider' => 'telegram_personal'
];

$client->channels->requestChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
  "code_length": 6,
  "code_type": "app",
  "expires_in": 60,
  "next_type": "app",
  "session_id": 1337,
  "status": "ok"
}

This endpoint request code for telegram personal

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/request_code

URL Parameters

Query Parameters

Request challenge code

Confirm code (telegram personal)

Confirmation type is code

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/confirm"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=telegram_personal&confirmation_type=code&code=2567"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#confirm-code-telegram-personal
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'provider' => 'telegram_personal',
  'confirmation_type' => 'code',
  'code' => 2567
];

$client->channels->confirmChannelCode(
  $companyId,
  $channelId,
  $parameters
);

Successful response:

{
  "result": "ok",
  "state": "enabled"
}

Confirmirmation type is password

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/confirm"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=telegram_personal&confirmation_type=password&password=123456"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#confirm-code-telegram-personal
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'provider' => 'telegram_personal',
  'confirmation_type' => 'password',
  'password' => 'qwerty123'
];

$client->channels->confirmChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
  "result": "ok",
  "state": "enabled"
}

This endpoint confirm telegram personal channel with two types: code, password

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/confirm

URL Parameters

Query Parameters

Confirmation type is code

Confirmation type is password

Request code (instagram only)

Request challenge code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/request_code"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=instagram&challenge_variant=0"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#request-code-instagram-only
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'challenge_variant' => $challengeVariant
];

$client->channels->requestChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
  "result": "ok"
}

Request two factor authentication code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/request_code"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=instagram&challenge_type=two_factor"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#request-code-instagram-only
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'challenge_type' => $challengeType
];

$client->channels->requestChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
  "result": "ok"
}

This endpoint request challenge or two factor authentication code.

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/request_code

URL Parameters

Query Parameters

Request challenge code

Request two factor SMS authentication code

Confirm code (instagram only)

Confirm challenge code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/confirm"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=instagram&confirmation_code=123456"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#confirm-code-instagram-only
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'confirmation_code' => $confirmationCode
];

$client->channels->confirmChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this.

Successful response:

{
  "result": "ok"
}

Two factor authentication required:

{
  "result": "ok",
  "data": {
    "two_factor_requires": true,
    "details": [
      { "value": 1, "key": "sms" },
      { "value": 2, "key": "recovery_code" },
      { "value": 3, "key": "totp" }
    ]
  }
}

Challenge required:

{
  "result": "ok",
  "data": {
    "confirmation_requires": true,
    "details": [
      { "value" => 1, "label" => "e*******e@example.org" },
      { "value" => 0, "label" => "+0 *** ***-**-00" }
    ]
  }
}

Confirm two factor authentication code:

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/channels/ID/confirm"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=instagram&confirmation_type=two_factor&confirmation_variant=3&confirmation_code=123456"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#confirm-code-instagram-only
 *
 * @param int $companyId Id of the compnay
 * @param int $channelId Id of the channel
 * @param array $parameters
 * @return Json|null
 */

$parameters = [
  'confirmation_type' => $confirmationType,
  'confirmation_variant' => $confirmationVariant,
  'confirmation_code' => $confirmationCode
];

$client->channels->confirmChannelCode(
  $companyId,
  $channelId,
  $parameters
);

The above command returns JSON structured like this:

{
  "result": "ok"
}

This endpoint submit challenge or two factor authentication code.

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<ID>/confirm

URL Parameters

Query Parameters

challenge code

two factor authentication code

Conversations

Conversation represents dialogue between you and the client. Currently only 1-1 conversations are supported. Each conversation has many messages.

Get All Conversations

curl "https://api.pact.im/p1/companies/COMPANY_ID/conversations"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * Gets all conversations
 * @link https://pact-im.github.io/api-doc/#get-all-conversations
 *
 * @param int id of the company
 * @param string Next page token geted from last request.
 * Not valid or empty token return first page
 * @param int Number of elements per page. Min 1, max 100, default: 50
 * @param string Change sorting direction. Available values: asc, desc. Default: asc.
 * @return Json|null
 */

// Get conversations:

$client->conversations->getConversations($companyId);

// Get conversations with parameters:

$client->conversations->getConversations(
  $companyId,
  $from,
  $per,
  $sort
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "conversations":[
         {
            "external_id":1,
            "name":"Friend",
            "channel_id":1,
            "channel_type":"whatsapp",
            "created_at":"2017-04-25T18:30:23.076Z",
            "created_at_timestamp":1603119600,
            "avatar":"/avatars/original/missing.png",
            "sender_external_id":"79260000001",
            "meta":{

            }
         }
      ],
      "next_page": "fslkfg2lkdfmlwkmlmw4of94wg34lfkm34lg"
   }
}

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/conversations

Query Parameters

URL Parameters

Create new conversation

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/conversations"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=whatsapp&phone=79250000001"

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/conversations"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "provider=telegram_personal&username=testuser&text=Hello"

<?php

/**
 * Creates new conversation
 * This endpoint creates conversation in the company
 * @link https://pact-im.github.io/api-doc/#create-new-conversation
 *
 * @param int id of the company
 * @param string conversation provider (e.g. "whatsapp")
 * @param array provider related params (e.g. for whatsapp is ["phone": "<phonenum>"])
 * @return Json|null
 */

$providerParams = [
  'phone' => $phone
];

$client->conversations->createConversation(
  $companyId,
  $provider,
  $providerParams
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "conversation":{
         "external_id":1,
         "name":"79250000001",
         "channel_id":1,
         "channel_type":"whatsapp",
         "created_at":"2017-11-11T10:17:10.655Z",
         "created_at_timestamp":1603119600,
         "avatar":"/avatars/original/missing.png",
         "sender_external_id":"79250000001",
         "meta":{

         }
      }
   }
}

This endpoint creates conversation in the company using whatsapp channel.

Create first message for whatsapp business provider

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/conversations

URL Parameters

Query Parameters for whatsapp channel

Query Parameters for telegram_personal channel

Update note for conversation

curl -X PUT "https://api.pact.im/p1/companies/COMPANY_ID/conversations/<ID>/note"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "note=your+note"

The above command returns JSON structured like this:

{
   "status":"updated"
}

This endpoint update note of conversation in the company.

HTTP Request

PUT https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<ID>/note

URL Parameters

Body Parameters

Get conversation details

curl "https://api.pact.im/p1/companies/COMPANY_ID/conversations/ID"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * Retrives conversation details from server
 * @link https://pact-im.github.io/api-doc/#get-conversation-details
 *
 * @param int id of company
 * @param int id of conversation
 * @return Json|null
 */

$client->conversations->getDetails($companyId, $conversationId)

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "conversation":{
         "external_id":1,
         "name":"79250000001",
         "channel_id":1,
         "channel_type":"whatsapp",
         "created_at":"2017-11-11T10:17:10.655Z",
         "created_at_timestamp":1603119600,
         "avatar":"/avatars/original/missing.png",
         "sender_external_id":"79250000001",
         "meta":{

         }
      }
   }
}

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<ID>

URL Parameters

Update assignee for conversation

curl -X PUT "https://api.pact.im/p1/companies/COMPANY_ID/conversations/<ID>/assign"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "assignee_id=42"

<?php

/**
 * Update assignee for conversation
 * This endpoint update assignee of conversation in the company using whatsapp channel
 * @link https://pact-im.github.io/api-doc/#update-assignee-for-conversation
 *
 * @param int id of company
 * @param int id of conversation
 * @param int id of user
 * @return Json|null
 */

$client->conversations->updateAssignee(
  $companyId,
  $conversationId,
  $assigneeId
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "conversation":{
         "external_id":1,
      }
   }
}

This endpoint update assignee the pact user to the conversation in the company.

HTTP Request

PUT https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<ID>/assign

URL Parameters

Query Parameters

Toggle bitrix block openlines

curl -X PUT "https://api.pact.im/p1/companies/COMPANY_ID/conversations/<ID>/toggle_bitrix_block_openlines"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "enabled=true"

The above command returns JSON structured like this:

{
  "status": "ok",
  "data": {
    "conversation": {
      "external_id": 91,
      "name": "Mikhail Tabunov",
      "channel_id": null,
      "channel_type": "whatsapp",
      "created_at": "2021-12-09T06:08:50.106Z",
      "created_at_timestamp": 1639030130,
      "avatar": "https://api.pact.im/avatars/original/missing.png",
      "sender_external_id": "79770000011",
      "meta": {},
      "last_message_at": 1639030130,
      "last_income_message_at": 0,
      "bitrix_block_openlines": true
    }
  }
}

This endpoint toggle bitrix_block_openlines param to the conversation in the company.

HTTP Request

PUT https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<ID>/toggle_bitrix_block_openlines

URL Parameters

Query Parameters

Upload attachment for message

The above command returns JSON structured like this:

{
   "status":"ok",
   "data": {
      "conversation": {
         "external_id": 1,
      }
   }
}

URL Parameters

Query Parameters

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<ID>/messages/attachments

Code example

<?php

/**
 * Сreates an attachment which can be sent in message
 * @link https://pact-im.github.io/api-doc/#upload-attachments
 *
 * @param int id of the company
 * @param int id of the conversation
 * @param Resource|StreamInterface|string file to upload
 * @return Json|null
 */

// Example with file on local:

$file_path = realpath('image.png');
$response_attach = $client->attachments->uploadAttachment($company, $conversation, $file_path);
$messages = $client->messages->sendMessage(
  $company,
  $conversation,
  $msg,
  [
    $response_attach->data->external_id
  ]
);

// Example with file url:

$file_url = 'https://en.wikipedia.org/wiki/Altai_Republic#/media/File:Katun.jpg';
$response_attach = $client->attachments->uploadAttachment($company, $conversation, $file_url);
$messages = $client->messages->sendMessage(
  $company,
  $conversation,
  $msg,
  [
    $response_attach->data->external_id
  ]
);

// Example with both variants:

$file_path = realpath('image.png');
$response_attach_1 = $client->attachments->uploadAttachment($company, $conversation, $file_path);

$file_url = 'https://en.wikipedia.org/wiki/Altai_Republic#/media/File:Katun.jpg';
$response_attach_2 = $client->attachments->uploadAttachment($company, $conversation, $file_url);

$messages = $client->messages->sendMessage(
  $company,
  $conversation,
  $msg,
  [
    $response_attach_1->data->external_id,
    $response_attach_2->data->external_id
  ]
);

Messages

Each message belongs to conversation. Message fields:

• id (Integer)
• channel_type (String) – whatsapp, instagram, etc..
• message (String) – message body
• income (Boolean) – whether message is income or outcome

Get conversation messages

curl "https://api.pact.im/p1/companies/COMPANY_ID/conversations/CONVERSATION_ID/messages"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * Get conversation messages
 * @link https://pact-im.github.io/api-doc/#get-conversation-messages
 *
 * @param int id of the company
 * @param int id of the conversation
 * @param string Next page token geted from last request.
 * Not valid or empty token return first page
 * @param int Number of elements per page. Default: 50
 * @param string We sort results by created_at. Change sorting direction. Avilable values: asc, desc. Default: asc.
 * @return Json|null
 */

$client->messages->getMessages(
  $companyId,
  $conversationId,
  $from,
  $per,
  $sort
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "messages":[
         {
            "external_id":47098,
            "channel_id":381,
            "channel_type":"whatsapp",
            "message":"Hello",
            "income":false,
            "created_at":"2017-09-17T12:44:28.000Z",
            "created_at_timestamp":1603119600,
            "attachments":[

            ]
         }
      ],
      "next_page": "fslkfg2lkdfmlwkmlmw4of94wg34lfkm34lg"
   }
}

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<CONVERSATION_ID>/messages

Query Parameters

URL Parameters

Send message

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/conversations/CONVERSATION_ID/messages"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "message=hello&attachments_ids[]=attachment_id"

<?php

/**
 * @link https://pact-im.github.io/api-doc/#send-message
 * @param int id of the company
 * @param int id of the conversation
 * @param string Message text
 * @param array<int>|null attachments
 */

$client->messages->sendMessage(
  $companyId,
  $conversationId,
  $message
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "id":18,
      "company_id":154,
      "channel":{
         "id":399,
         "type":"whatsapp"
      },
      "conversation_id":8741,
      "state":"trying_deliver",
      "message_id":null,
      "details":null,
      "created_at":1510396057
   }
}

This endpoint delivers message to the client under specified conversation.

There are two delivery modes: synchronous and asyncronous. If message_id field in response is null or empty – it means asyncronous delivery.

You’ll receive a webhook with the delivery status if delivery is async.

You can check operation result manually here: Jobs

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<CONVERSATION_ID>/messages

URL Parameters

Body Parameters

Important: Some messengers support only text or only attachment in one message. For example, whatsapp allows to attach a caption for an image but not allows to attach a caption to a PDF document. Multiple attachments are allowed only for vkontakte

Interactive WABA message with buttons example

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/conversations/CONVERSATION_ID/message"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "{ "message": "wassup", "interactive": { "type": "button", "buttons": ["fine", "awesome"] } }"

Upload attachments

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/conversations/CONVERSATION_ID/messages/attachments"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -F "file=@path/to/local/file"

<?php

$file_path = realpath('image.png');
$response_attach_1 = $client->attachments->uploadAttachment($company, $conversation, $file_path);

$file_url = 'https://en.wikipedia.org/wiki/Altai_Republic#/media/File:Katun.jpg';
$response_attach_2 = $client->attachments->uploadAttachment($company, $conversation, $file_url);

$messages = $client->messages->sendMessage(
  $company,
  $conversation,
  $msg,
  [
    $response_attach_1->data->external_id,
    $response_attach_2->data->external_id
  ]
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "external_id":1
   }
}

This endpoint creates an attachment which can be sent in message.

HTTP Request

POST https://api.pact.im/p1/companies/<COMPANY_ID>/conversations/<CONVERSATION_ID>/messages/attachments

URL Parameters

Query Parameters

Waba templates

A company with a whatsapp_business channel can have waba templates

Get waba templates

curl "https://api.pact.im/p1/companies/COMPANY_ID/waba_templates"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
  * Gets WhatsApp Business templates
  * @link https://pact-im.github.io/api-doc/#waba-templates
  *
  * @param int id of the company
  * @param string Next page token geted from last request.
  * Not valid or empty token return first page
  * @param int Number of elements per page. Min 1, max 100, default: 50
  * @param string Change sorting direction. Available values: asc, desc. Default: asc.
  * @return Json|null
  */

# Simple request

$client->companies->getWabaTemplates(
  $companyId
);

# Pagination

$client->companies->getWabaTemplates(
  $companyId,
  $from,
  $per,
  $sort
);

returns JSON structured like this:

{
  "status":"ok",
  "data":{
    "waba_templates":[
      {
        "id":7754,
        "company_id":72562,
        "name":"Шаблон с переменной",
        "waba_id":"1_shablon_kakoito",
        "body":"Тестовый шаблон с какой то переменной {{1}}",
        "substitutions_count":1,
        "position":7754
      }
    ]
  }
}

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/waba_templates

Query Parameters

URL Parameters

Webhooks

Webhooks is a way to notify you about new messages or other events in our system. It’s mandatory to use webhooks for 99% integrations with our API.

Endpoint with webhook_url must response with http status code 200 if endpoint received webhook.

Webhook could be repeated up to 10 times within 60 sec delay if response status code is not equal 200. After 10 retries webhook will be dropped and nevery delivered.

New conversation

The above command returns JSON structured like this:

{
   "type":"conversation",
   "event":"new",
   "data":{
      "external_id":1,
      "name":"Sender Name",
      "avatar_url": "https://cdn.pact.im/conversations/avatars/000/000/000/original/open-uri00000000-00000-0p0igg0?0000000000",
      "channel_id":1,
      "channel_type":"whatsapp",
      "created_at":"2017-11-11 12:45:53 UTC",
      "created_at_timestamp":1603118584,
      "last_message_at":null,
      "last_income_message_at":null,
      "sender_external_id":"79250000001"
   }
}

When

• Client sends new message first time.
• You sent message to new client. Message was delivered, conversation was created.

Update conversation

The above command returns JSON structured like this:

{
   "type":"conversation",
   "event":"update",
   "data":{
      "external_id":1,
      "name":"Sender Name",
      "avatar_url": "https://cdn.pact.im/conversations/avatars/000/000/000/original/open-uri00000000-00000-0p0igg0?0000000000",
      "channel_id":1,
      "channel_type":"whatsapp",
      "created_at":"2017-11-11 12:45:53 UTC",
      "created_at_timestamp":1603118584,
      "last_message_at":null,
      "last_income_message_at":null,
      "sender_external_id":"79250000001"
   }
}

When

• When conversation with such an sender_external_id already exists and new data is received the sender_name and sender_avatar_url.

New message

The above command returns JSON structured like this:

{
   "type":"message",
   "event":"new",
   "data":{
      "external_id":1,
      "external_public_id":1,
      "channel_id":1,
      "channel_type":"whatsapp",
      "channel":{
        "id": 1,
        "type": "whatsapp"
      },
      "conversation_id":1,
      "message":"Message body",
      "location": {},
      "income":true,
      "created_at":"2017-11-11 12:45:53 UTC",
      "created_at_timestamp":1603118584,
      "ack":1,
      "attachments":[],
      "job_id":1
   }
}

When

• Client sent new message.
• You sent message to client.

Message delivery/read status

The above command returns JSON structured like this:

{
    "type": "message",
    "event": "ack",
    "data": {
        "external_id": 1,
        "channel": {
            "id": 1,
            "type": "whatsapp"
        },
        "conversation_id": 1,
        "ack": 3
    }
}

When

• Message was delivered
• Message was read

Possible statuses:

• -1 : Message is in preparing to deliver state
• ` 0 : Message is in delivering` state
• ` 1` : Message was sent
• ` 2` : Message was delivered
• ` 3` : Message was read

If message in a -1 state - message may not be delivered. You must to care about message delivering by yourself.

Delivery job executed

The above command returns JSON structured like this:

{
   "type":"job",
   "event":"executed",
   "data":{
      "id":1,
      "result":"DELIVERED",
      "message_id":1,
      "date":1510404738
   }
}

When

• You sent message in async mode. Delivery job was executed and delivery result is known.

Possible results:

• DELIVERED
• NOT DELIVERED

If message is NOT DELIVERED we append reason filed with reason information.

Whatsapp: new QR-code

The above command returns JSON structured like this:

{
   "type":"qr_code",
   "event":"new",
   "company_id":1,
   "channel_id":1,
   "data":"BASE64 QR-CODE image string"
}

When

• You are connecting whatsapp channel in your company
• User logged out in WhatsApp app

Whatsapp: channel connected sucessfuly

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"information",
   "data":{
      "message":"authorized",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

QR-code was scanned successfuly

Whatsapp: phone offline

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"phone offline",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

Device with WhatsApp application is unreachable. We can’t work with whatsapp while phone is offline.

Whatsapp: phone online

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"phone online",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

Device with WhatsApp application is reachable again.

Whatsapp: channel not available

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"unavailable",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

Someone started session at web.whatsapp.com or user similar integration. We can’t work with whatsapp while Whatsapp WEB is open.

Whatsapp: channel disabled

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"disabled",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

By some reason whatsapp session is not alive anymore (for example, user exited on the device or whatsapp expired session)

Whatsapp: trying to resume channel work

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"trying_resume_work",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

We’re trying to resume work after previous conflict state

Whatsapp: synchronization completed

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"critical",
   "data":{
      "message":"synchronized",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "timestamp":1603119138,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

• Whatsapp channel was connected and syncronisation was completed
• Syncronisation after work resume

Instagram: changed state to disabled

The above command returns JSON structured like this:

{
   "type":"system",
   "severity":"information",
   "data":{
      "message":"IG was set DISABLED",
      "date":"2017-11-11 12:45:53 UTC",
      "date_timestamp":1603118584,
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

• Service message successfully delivered
• Service message delivery failed

Group chats: new conversation

The above command returns JSON structured like this:

{
   "type": "group_conversation",
   "event": "new",
   "data":{
      "name": "Group name",
      "avatar_url": null,
      "channel_id": 1,
      "created_at": "2023-04-28T12:34:01.937Z",
      "external_id": 1,
      "channel_type": "whatsapp",
      "last_message_at": null,
      "sender_external_id": "120363148147828952",
      "created_at_timestamp": 1682685241,
      "last_income_message_at": null
   }
}

When

• Group chat member sends new message first time.
• You send a message to a group chat. Message was delivered, conversation was created.

Group chats: new group message

The above command returns JSON structured like this:

{
    "type": "group_message",
    "event": "new",
    "data": {
        "ack": 0,
        "income": true,
        "channel": {
            "id": 1,
            "type": "whatsapp"
        },
        "message": "Message body",
        "location": null,
        "channel_id": 1,
        "created_at": "2023-04-05T12:00:52.000Z",
        "attachments": [],
        "external_id": 1,
        "channel_type": "whatsapp",
        "conversation_id": 1,
        "external_public_id": "79000000000",
        "created_at_timestamp": 1680696052,
        "external_created_at_timestamp": 1680696052
    }
}

When

• Group chat member sent new message.
• You send a message to a group chat.

Group chats: message delivery/read status

The above command returns JSON structured like this:

{
   "type": "group_message",
   "event": "ack",
   "data": {
      "channel": {
         "id": 65706,
         "type": "whatsapp"
      },
      "timestamp": 1682658436,
      "external_id": 1,
      "participant": "79000000000",
      "conversation_id": 1,
      "external_public_id": null,
      "ack": 3
   }
}

When

• Message was delivered
• Message was read

Possible statuses:

• ` 0 : Message is in delivering` state
• ` 1` : Message was sent
• ` 2` : Message was delivered
• ` 3` : Message was read

Group chats: new active member

The above command returns JSON structured like this:

{
   "type": "group_conversation_contact",
   "event": "new",
   "data": {
      "contact": {
         "external_public_id": "79000000000"
      },
      "channel_id": 65706,
      "channel_type": "whatsapp",
      "date_timestamp": 1682652148,
      "conversation_id": 1
   }
}

When

• Group chat member sent new message first time.

Message delivery Jobs

Get Job details

curl "https://api.pact.im/p1/companies/COMPANY_ID/channels/<CHANNEL_ID>/jobs/<ID>"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"

<?php

/**
 * This method return info about message delivery job
 * @link https://pact-im.github.io/api-doc/?shell#message-delivery-jobs
 *
 * @param int id of the company
 * @param int id of the channel
 * @param int id of the job
 * @return Json|null
 */

$client->jobs->getJob(
  $companyId,
  $channelId,
  $jobId
);

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "id":1,
      "company_id":1,
      "channel":{
         "id":1,
         "type":"whatsapp"
      },
      "conversation_id":1,
      "state":"delivered",
      "message_id":1,
      "details":{
         "result":"DELIVERED"
      },
      "created_at":1510393147
   }
}

This endpoint returns information about message delivery job

HTTP Request

GET https://api.pact.im/p1/companies/<COMPANY_ID>/channels/<CHANNEL_ID>/jobs/<ID>

URL Parameters

Message may be DELIVERED of NOT DELIVERED.

Message will be NOT DELIVERED if case when:

• Integration doesn’t work
• Contact is not present
• Message was rejected by external system

Private API V2

Authentication V1

curl -X POST "https://api.pact.im/api/p2/some_endpoint" \
--header "Content-Type: application/json" \
--data '{
    "private_api_token": "YOUR_API_TOKEN",
    "another_parameter": "value"
  }'

curl -X POST "https://api.pact.im/api/p2/some_endpoint" \
--header "Content-Type: application/json" \
--header 'X-Private-Api-Token: YOUR_API_TOKEN' \
--data '{
    "another_parameter": "value"
  }'

curl -X POST "https://api.pact.im/api/p2/some_endpoint?private_api_token=<YOUR_API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
    "another_parameter": "value"
  }'

Example of auth error:

{
  "errors": [
    {
      "status": 401,
      "code": "unauthorized",
      "title": "Unauthorized",
      "detail": "No token provided"
    }
  ]
}

To facilitate a smooth transition, we have decided to temporarily keep the old authentication method and label it as V1

For V1 authentication, a private api token will be used as before. Use it for all requests. You can use one of these variants you like:

• pass private_api_token param in json payload
• pass X-Private-Api-Token param in headers
• pass private_api_token as url param

See examples on the right side –>

Authentication V2

curl -X GET "API_ENDPOINT_HERE" \
--header "X-Api-Token: YOUR_AUTHENTICATION_TOKEN"

All requests to Pact API must be authenticated.

Pact expects for an authentication token to be included in all API requests to the server in a header that looks like the following:

X-Api-Token: YOUR_AUTHENTICATION_TOKEN

Here are steps to receive your Authentication Token

1. Set webhook_url in your user settings at https://msg.pact.im/account
2. To receive security code on your webhook_url send request

POST https://api.pact.im/api/verification?locale=ru&source=private_api_v2&phone=YOUR_PHONE

1. To receive Authentication Token and Refresh token send

POST https://api.pact.im/api/sign_in?phone=YOUR_PHONE&code=SECURITY_CODE

Authentication Token in Authentication-Token header and Refresh Token in Refresh-Token header (lifespan is 1 hour / 30 days respectivly). Refresh Token is one use only.

To receive new pair of tokens send with a header that looks like this

X-Api-Refresh-Token: Refresh Token

POST https://api.pact.im/api/refresh_token

Messages

With the help of what is described in this section you can:

• Get messages of the conversation
• Get concrete message of the conversation
• Send message to existing conversation
• Write first message (when there is no conversation)

curl -X GET 'https://api.pact.im/api/p2/conversations/CONVERSATION_ID/messages' \
--header 'Content-Type: application/json' \
--data '{
    "private_api_token": YOUR_API_TOKEN,
    "company_id": COMPANY_ID,
    "page": 1
  }'

The above command returns JSON structured like this:

{
  "messages": [
    {
      "id": 13224,
      "external_id": "b91c9b99-7c24-40a7-8b52-1d80b5b3e158",
      "company_id": 52204,
      "conversation_id": 18642850,
      "contact_id": 549645235,
      "replied_to_id": null,
      "created_at": "2024-11-12T06:28:10.907Z",
      "external_created_at": "2024-11-12T06:28:10.000Z",
      "income": false,
      "status": "read",
      "message": null,
      "reactions": [],
      "details": null,
      "attachments": [
        {
          "id": 53431944,
          "message_id": 13224,
          "file_name": "p4ct-br0ws3r-v01ce-r3c0rd.ogg",
          "mime_type": "audio/ogg",
          "size": 39185,
          "attachment_url": "https://cdn.pact.im/uploads/storage/attachment/file/a1dd41f80c3ae85beb355a38ea3f5b53.ogg",
          "push_to_talk": true
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "entries_count": 1,
    "per_page": 150
  }
}

Get Conversation Messages

Returns paginated messages of the conversation sorted by external_created_at field

By default, 150 messages will be returned per page

Read more about pagination

HTTP Request

GET https://api.pact.im/api/p2/conversations/<CONVERSATION_ID>/messages

URL Parameters

Body Parameters (Json)

Response Parameters

Message object

• id (Integer) - ID
• external_id (String) - External message ID from provider (it uses for message replies)
• company_id (Integer) - ID of the company
• conversation_id (Integer) - ID of the conversation
• contact_id (Integer) - ID of the message contact
• replied_to_id (String) - External ID of the message to which this message is a reply
• created_at (Time) - Time we created this message in our db
• external_created_at (Time) - Time from provider (as a rule, the time of direct sending of the message)
• income (Boolean) – Whether message is income or outgoing
• status (String) - Status of the message (can be created, sent, delivered, read, error)
• message (String) – Message body
• reactions (Array) – Message reactions
• details (Object) - Data containing reason why message was not delivered (if it is)
• attachments (Array) – Array of message attachment objects (if it has)

Attachment object

• id (Integer) - ID
• message_id (Integer) - ID of the message
• file_name (String) - Original file name
• mime_type (String) - Mime type (audio/ogg for ex.)
• size (Integer) - File size in bytes
• attachment_url (String) - Url of the file
• preview_url (String) - Url of the image preview (if it is image)
• aspect_ratio (Float) - Aspect ratio (if it is image)
• data (Object) - width and height (if it is image)
• push_to_talk (Boolean) - Voice or just audio file (if it is audio)

Meta object. More info in the paragraph about pagination

curl -X GET 'https://api.pact.im/api/p2/conversations/CONVERSATION_ID/messages/MESSAGE_ID' \
--header 'Content-Type: application/json' \
--data '{
    "private_api_token": YOUR_API_TOKEN,
    "company_id": COMPANY_ID
  }'

The above command returns JSON structured like this:

{
  "message": {
    "id": 1134326991,
    "external_id": "34577",
    "company_id": 86605,
    "conversation_id": 209752626,
    "contact_id": 1583160940,
    "replied_to_id": null,
    "created_at": "2025-02-05T09:01:48.514Z",
    "external_created_at": "2025-02-05T09:01:47.000Z",
    "income": true,
    "status": "created",
    "message": "",
    "reactions": [],
    "details": null,
    "attachments": []
  }
}

Get Conversation Message

Returns message of the conversation by id

HTTP Request

GET https://api.pact.im/api/p2/conversations/<CONVERSATION_ID>/messages/<MESSAGE_ID>

URL Parameters

Body Parameters (Json)

Response Parameters

Message object

curl -X POST 'https://api.pact.im/api/p2/conversations/CONVERSATION_ID/messages' \
--header 'Content-Type: application/json' \
--data '{
    "private_api_token": YOUR_API_TOKEN,
    "company_id": COMPANY_ID,
    "text": "test"
  }'

The above command returns JSON structured like this:

{
  "message": {
    "id": 239,
    "external_id": null,
    "company_id": 52204,
    "conversation_id": 18642824,
    "contact_id": 3,
    "replied_to_id": null,
    "created_at": "2025-02-13T14:07:51.582Z",
    "external_created_at": "2025-02-13T14:07:51.000Z",
    "income": false,
    "status": "sent",
    "message": "Hello World!",
    "reactions": [],
    "details": null,
    "attachments": []
  }
}

Send Message To Existing Conversation

Allows to send message to existing conversation

HTTP Request

POST https://api.pact.im/api/p2/conversations/<CONVERSATION_ID>/messages

URL Parameters

Body Parameters (Json)

Response Parameters

Message object

curl -X POST 'https://api.pact.im/api/p2/messages' \
--header 'Content-Type: application/json' \
--data '{
    "private_api_token": YOUR_API_TOKEN,
    "company_id": COMPANY_ID,
    "text": "test"
  }'

The above command returns JSON structured like this:

{
  "message": {
    "id": 239,
    "external_id": null,
    "company_id": 52204,
    "conversation_id": 18642824,
    "contact_id": 3,
    "replied_to_id": null,
    "created_at": "2025-02-13T14:07:51.582Z",
    "external_created_at": "2025-02-13T14:07:51.000Z",
    "income": false,
    "status": "sent",
    "message": null,
    "reactions": [],
    "details": null,
    "attachments": [
      {
        "id": 5,
        "message_id": 239,
        "file_name": "5287346531311154701.png",
        "mime_type": "image/jpeg",
        "size": 65030,
        "attachment_url": "https://cdn.pact.im/uploads/storage/attachment/file/a845515c570e285e2ae22d9d493e3abc.png",
        "preview_url": "https://cdn.pact.im/uploads/storage/attachment/file/small-3a46073e438fa82c6c04fd2ff3e1cfef.png",
        "aspect_ratio": 0.46,
        "data": {
          "width": 591,
          "height": 1280
        }
      }
    ]
  }
}

Write First Message

Allows to send message when no conversation with this recipient exists

Only these providers available at this moment: whatsapp, telegram_personal, whatsapp_business

HTTP Request

POST https://api.pact.im/api/p2/messages

Body Parameters (Json)

You should use waba_id if you want to write first with whatsapp_business provider. More about waba templates

Response Parameters

Message object

Pagination

Example of response with pagination:

{
  "companies": [
    {
      "id": 26,
      "name": "Company 26"
    },
    {
      "id": 27,
      "name": "Company 27"
    },
    {
      "id": 28,
      "name": "Company 28"
    },
    {
      "id": 29,
      "name": "Company 29"
    }
  ],
  "meta": {
    "page": 2,
    "entries_count": 4,
    "per_page": 25
  }
}

Api V2 supports pagination. Pagination is a method used to divide large sets of data into smaller, more manageable chunks, which are returned page by page. This helps improve performance and reduces the amount of data transferred in a single request

If there are more results than can fit on a single page, you can request additional pages by increasing the page parameter. The response will include metadata indicating the current page, the number of records on that page, and the total number of records per page

For example, if there are 100 records and per_page is set to 25, there will be 4 pages available. You can navigate through the pages by changing the page parameter in your request

Pagination Parameters In Request

Response Parameters

Meta object

• page (Integer) - Number of current page
• entries_count (Integer) - Number of returned entries
• per_page (Integer) - Entries per page

Request Rate Limits

Error like this will be returned when request limit was overed:

{
  "errors": [
    {
      "status": 429,
      "code": "too_many_requests",
      "title": "Too many requests error",
      "detail": "Please wait for 50 seconds"
    }
  ]
}

Api V2 has request rate limits

To ensure system stability, prevent abuse, and optimize performance, our API enforces rate limits. These limits control the number of requests a single user can make within a specific time frame

Why Are Rate Limits Necessary? Rate limits help to: Protect the system from overload – limiting request frequency prevents sudden spikes in server load. Prevent abuse. Ensure fair resource distribution – all users get equal access to the API, preventing excessive usage by a single client from affecting others. Optimize performance – keeps the server running smoothly and predictably without sudden performance drops. If the rate limit is exceeded, the server will return an error with the HTTP status code 429 Too Many Requests. In such cases, it is recommended to retry the request after some time

Some endpoints have several rate limits to control both short-term and long-term request bursts. This multi-limit approach balances responsiveness and fairness, allowing high-frequency but controlled API usage

The rate limits depending on the type of request:

Get messages of the conversation:

• Maximum 20 requests per minute

Get concrete message of the conversation:

• Maximum 20 requests per minute

Send message to existing conversation:

• Maximum 5 requests per second
• Maximum 30 requests per minute

Write first message:

• Maximum 5 requests per second
• Maximum 30 requests per minute

Webhooks

Webhook when message was sent:

{
  "event": "create",
  "type": "message",
  "object": {
    "id": 22891,
    "external_id": null,
    "company_id": 52249,
    "conversation_id": 18643195,
    "contact_id": 549645443,
    "replied_to_id": null,
    "created_at": "2025-02-17T14:46:29.074Z",
    "external_created_at": "2025-02-17T14:46:29.000Z",
    "income": false,
    "status": "sent",
    "message": "Текст в заголовке\nШаблон с кнопками и текстом в заголовке",
    "reactions": [],
    "details": null,
    "attachments": []
  }
}

Webhook when message was delivered:

{
  "event": "update",
  "type": "message",
  "object": {
    "id": 22891,
    "external_id": "wamid.HBgLNzk1MTY1ODE2MTIVAgARGBI3NzUyM0MxNkYxRjFGM0U0NkMA",
    "company_id": 52249,
    "conversation_id": 18643195,
    "contact_id": 549645443,
    "replied_to_id": null,
    "created_at": "2025-02-17T14:46:29.074Z",
    "external_created_at": "2025-02-17T14:46:29.000Z",
    "income": false,
    "status": "delivered",
    "message": "Текст в заголовке\nШаблон с кнопками и текстом в заголовке",
    "reactions": [],
    "details": null,
    "attachments": []
  }
}

Webhook when message was failed:

{
  "event": "update",
  "type": "message",
  "object": {
    "id": 22892,
    "external_id": "wamid.HBgLNzk2MDk4MjMwODkVAgARGBJCMjM1NEU1Q0UwMzcyNEI2NEUA",
    "company_id": 52249,
    "conversation_id": 18643298,
    "contact_id": 549645443,
    "replied_to_id": null,
    "created_at": "2025-02-17T15:07:24.968Z",
    "external_created_at": "2025-02-17T15:07:24.000Z",
    "income": false,
    "status": "error",
    "message": "Текст в заголовке\nШаблон с кнопками и текстом в заголовке",
    "reactions": [],
    "details": {
      "result": "NOT DELIVERED",
      "internal_reason": {
        "errors": [
          {
            "code": 131026,
            "error_data": {
              "details": "Message Undeliverable."
            },
            "message": "Message undeliverable",
            "title": "Message undeliverable"
          }
        ]
      }
    },
    "attachments": []
  }
}

With Api V2 release we are starting to send new type of webhooks. More standardized, opimized and informative

Webhook Parameters

• event (String) - Type of the event (create, update, delete)
• type (String) - Object type (message, conversation, …)
• object (Object) - Object with its fields

Message Webhooks:

When a message is sent (after sending message to existing conversation for ex), the service triggers a webhook with the create event and the status sent. At this stage, external_id is null because we have not received answer from provider at this moment

Once the message is successfully sent, a webhook with the update event is triggered, where:

The status is updated to delivered, external_id is assigned

If a message fails to send, the status is updated to error, and the details field contains the reason for the failure. In this case, the message failed to send due to recipient does not have whatsapp_business

For incoming messages you will receive only one webhook with event create and message status created

Webhook Message Object Parameters

Message object

Errors

The Pact API uses the following error codes:

Terms and conditions

• You will NOT use this API for spam, massive sending, etc.
• You will NOT use this API if you’re NOT agree with these terms and conditions.
• We have the right to block any user of Pact.im API (without refund) if these conditions are not met.

Legal

This API is in no way affiliated with, authorized, maintained, sponsored or endorsed by

• WhatsApp or any of its affiliates or subsidiaries
• Instagram or any of its affiliates or subsidiaries

This is an independent and unofficial API. Use at your own risk.