NAV
shell php

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

Parameter Required Validations Description
from false Must be a String not more than 255 symbols Next page token geted from last request. Not valid or empty token return first page
per false Must be a number between 1 and 100 Number of elements per page. Default: 50
sort_direction false Must be a String We sort results by id. Change sorting direction. Avilable values: asc, desc. Default: asc.

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

Parameter Description
ID ID of the company for update

Query Parameters

Parameter Required Validations Description
name false Must be a String not more than 255 symbols Company name
phone false Must be a String Official company phone number or phone number of contact person
description false Must be a String Company description
webhook_url false Must be a String Endpoint for webhooks
hidden false Must be a Boolean Hide/Show a company in the Pact web interface

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

Parameter Required Validations Description
name true Must be a String not more than 255 symbols Company name
phone false Must be a String Official company phone number or phone number of contact person
description false Must be a String Company description
webhook_url false Must be a String Endpoint in the Internet which can receive webhooks

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:

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

Parameter Required Validations Description
from false Must be a String not more than 255 symbols Next page token geted from last request. Not valid or empty token return first page
per false Must be a number between 1 and 100 Number of elements per page. Default: 50
sort_direction false Must be a String We sort results by id. Change sorting direction. Avilable values: asc, desc. Default: asc.

URL Parameters

Parameter Description
COMPANY_ID ID of the company

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

Parameter Description
COMPANY_ID ID of the company

Query Parameters

Create whatsapp channel
Parameter Required Validations Description
provider true Must be whatsapp  
sync_messages_from false timestamp Only messages created after sync_messages_from will be synchronized. Not older than one month.
phone true string  
Create whatsapp business channel (dialog360 by token)
Parameter Required Validations Description
provider true Must be whatsapp_business  
hosting_type true Must be a cloud, onpremise Hosting platform type
token true Must be a String Token for auth.
subtype false Must be a regular, unlim, no_write_first Tarif name
Create whatsapp business channel (dialog360 by channel_id)
Parameter Required Validations Description
provider true Must be whatsapp_business  
hosting_type true Must be a cloud, onpremise Hosting platform type
dialog360_channel_id true Must be a String channel_id for auth
dialog360_client_id false Must be a String client_id for auth
account_name false Must be a String Account name for waba profile
subtype false Must be a regular, unlim, no_write_first Tarif name
Create avito channel
Parameter Required Validations Description
provider true Must be avito  
login true Must be a String avito client_id
password true Must be a String avito client secret
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.

Parameter Required Validations Description
provider true Must be instagram_business  
private_api_token true String User privat token
data true Hash Data from Instagram that was transferred to redirect_url
phone true String User phone
token true String Instagram token
Create facebook/vkontakte/vkontakte_direct/telegram/viber channel
Parameter Required Validations Description
provider true Must be one of: facebook, vkontakte, vkontakte_direct, telegram, viber Shows which provider you want to connect
token true Must be a String Token for auth.
Create telegram personal channel (by qr code)
Parameter Required Validations Description
provider true Must be telegram_personal  
via_qr_code true boolean Must be a ‘true’
sync_messages_from false timestamp Only messages created after sync_messages_from will be synchronized. Not older than one month.
Create telegram personal channel (by digital code)
Parameter Required Validations Description
provider true Must be telegram_personal  
phone true Must be a String Phone number. Example: ‘7999999999’
sync_messages_from false timestamp Only messages created after sync_messages_from will be synchronized. Not older than one month.

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

For facebook/vkontakte/vkontakte_direct/telegram/viber/instagram_business channels
Parameter Required Validations Description
token true Must be a String

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel for disable

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

Parameter Required Validations Description
phone true Must be in format 79250000001 Contact phone number
message false Must be String Message text. For regular Whatsapp channel only
template false Must be Object Template data. For Whatsapp Business channel only

Whatsapp Business Template Parameters

Parameter Required Validations Description
id true Must be String ID of registered template
language_code true Must be String Language code of registered template ('en', 'ru', etc)
parameters true Must be Array Template substitution 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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel
provider whatsapp

Query Parameters

Request challenge code
Parameter Required Validations Description
provider true Must be whatsapp  

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

Request challenge code
Parameter Required Validations Description
provider true Must be telegram_personal  

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

Confirmation type is code
Parameter Required Validations Description
provider true Must be telegram_personal  
confirmation_type true Must be code  
code true Must be a Number Example: 1234
Confirmation type is password
Parameter Required Validations Description
provider true Must be telegram_personal  
confirmation_type true Must be password  
password true Must be a String Example: qwerty123

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

Request challenge code
Parameter Required Validations Description
provider true Must be instagram  
challenge_variant true    
Request two factor SMS authentication code
Parameter Required Validations Description
provider true Must be instagram  
challenge_type true Must be two_factor  

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the channel

Query Parameters

challenge code
Parameter Required Validations Description
provider true Must be instagram  
confirmation_code true Must be a String  
two factor authentication code
Parameter Required Validations Description
provider true Must be instagram  
confirmation_type true Must be two_factor  
confirmation_variant true Must be a Integer Variant from request code response (data->details->value). Typicaly 1, 2 or 3.
confirmation_code true Must be a String  

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

Parameter Required Validations Description
from false Must be a String not more than 255 symbols Next page token geted from last request. Not valid or empty token return first page
per false Must be a number between 1 and 100 Number of elements per page. Default: 50
sort_direction false Must be a String We sort results by id. Change sorting direction. Avilable values: asc, desc. Default: asc.

URL Parameters

Parameter Description
COMPANY_ID ID of the company

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

Parameter Description
COMPANY_ID ID of the company

Query Parameters for whatsapp channel

Parameter Required Validations Description
provider true Must be whatsapp Shows what you want to create new conversation in the whatsapp channel
phone true Must be in format 79250000001 Contact phone number

Query Parameters for telegram_personal channel

Parameter Required Validations Description
provider true Must be telegram_personal Shows what you want to create new conversation
phone true Must be in format 79250000001 Contact phone number
username true String Username
text true String Message text
send_to_crm false boolean Sync initializing message to CRM integrations. Default: true

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

Parameter Description
COMPANY_ID ID of the company
CONVERSATION_ID ID of the conversation

Body Parameters

Parameter Required Validations Description
note true Must be String Note text

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the conversation

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the conversation

Query Parameters

Parameter Required Validations Description
assignee_id false Must be an integer User id

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

Parameter Description
COMPANY_ID ID of the company
ID ID of the conversation

Query Parameters

Parameter Required Validations Description
enabled false Must be a boolean Enabled status

Upload attachment for message

The above command returns JSON structured like this:

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

URL Parameters

Parameter Description
COMPANY_ID ID of the company
ID ID of the conversation

Query Parameters

Parameter Required Validations Description
file false Must be a file Uploaded file
file_url false Must be a file url File url
push_to_talk false Boolean To send audio files as voice messages
metadata: {“data”:{“width”: integer, “height”: integer}} false Json Determine the size of attachments (image, video) in the mobile version

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:

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

Parameter Required Validations Description
from false Must be a String not more than 255 symbols Next page token geted from last request. Not valid or empty token return first page
per false Must be a number between 1 and 100 Number of elements per page. Default: 50
sort_direction false Must be a String We sort results by created_at. Change sorting direction. Avilable values: asc, desc. Default: asc.

URL Parameters

Parameter Description
COMPANY_ID ID of the company
CONVERSATION_ID ID of the conversation

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

Parameter Description
COMPANY_ID ID of the company
CONVERSATION_ID ID of the conversation

Body Parameters

Parameter Required Validations Description
message false Must be String Message text
attachments_ids false Must be an Array with attachments ids IDs of previously uploaded attachments.
interactive false object Interactive message configuration (only WABA channel)
send_to_crm false boolean Sync this message to CRM integrations. If not specified the default value is ‘true’

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

Parameter Description
COMPANY_ID ID of the company
CONVERSATION_ID ID of the conversation

Query Parameters

Parameter Required Validations Description
file false Must be a File. Mutually exclusive with file_url Attachment file
file_url false Must be a url (http or https). mutually exclusive with file Attachment file url

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

Parameter Required Validations Description
from false Must be a String not more than 255 symbols Next page token geted from last request. Not valid or empty token return first page
per false Must be a number between 1 and 100 Number of elements per page. Default: 50
sort_direction false Must be a String We sort results by created_at. Change sorting direction. Avilable values: asc, desc. Default: asc.

URL Parameters

Parameter Description
COMPANY_ID ID of the company

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

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

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

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

Possible statuses:

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

Possible results:

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

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

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

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

Possible statuses:

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

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

Parameter Description
COMPANY_ID ID of the company
CHANNEL_ID ID of the channel
ID ID of the job

Message may be DELIVERED of NOT DELIVERED.

Message will be NOT DELIVERED if case when:

Private API V2

Authentication

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

Examples

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

Errors

The Pact API uses the following error codes:

HTTP Status Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
402 Payment Required – Paywoll enabled for the company, you must pay before doing API requests
403 Forbidden – The endpoint is unavailable for you
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested resource has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many requests! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
502 Bad Gateway – We’re temporarially offline for maintanance. Please try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Terms and conditions

Legal

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

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