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

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,
  'do_not_mark_as_read' => $doNotMarkAsRead,
  // ...
];

$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
);

Create instagram 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 string $login Instagram login
 * @param string $password Instagram passowrd
 * @param DateTimeInterface $syncMessagesFrom Only messages created after will be synchronized
 * @param bool $syncComments
 * @return Json|null
 */

$client->channels->createChannelInstagram(
  $companyId,
  $login,
  $password,
  $syncMessagesFrom,
  $syncComments
);

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
do_not_mark_as_read false boolean Do not mark chats as read after synchronization

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 channel

Parameter Required Validations Description
provider true Must be instagram  
login true Must be a String Instagram login
password true Must be a String Instagram password. We don’t save password, only authorization cookies
sync_messages_from false timestamp Only messages created after sync_messages_from will be synchronized
sync_comments false boolean Enable comment sync

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

Parameter Required Validations Description
provider true Must be telegram_personal  
username true Must be a String Phone number. Example: ‘7999999999’
sync_messages_from false timestamp Only messages created after sync_messages_from will be synchronized

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

Parameter Required Validations Description
login true Must be a String Instagram login
password true Must be a String Instagram password. We don’t save password, only authorization cookies

For facebook/vkontakte/vkontakte_direct/telegram/viber 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 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 (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"
<?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

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

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

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

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)

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"

returns JSON structured like this:

{
   "status":"ok",
   "data":{
      "waba_templates":[
        {
          "id": 321,
          "company_id": 123,
          "name": "template_name",
          "waba_id": "template_id",
          "body": "Здравствуйте, 1",
          "substitutions_count": 2
        }
      ],
      "next_page": "fslkfg2lkdfmlwkmlmw4of94wg34lfkm34lg"
   }
}

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

Service messages: delivery status

The above command returns JSON structured like this:

{
   "type":"service_messages",
   "event":"update",
   "data":{
      "id": 42,
      "delivered": true,
      "delivered_at":"2018-12-5 15:05:14 UTC",
      "delivered_at_timestamp":1603118584,
      "delivered_via":"whatsapp"
   }
}

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:

Service messages

Send message

curl -X POST "https://api.pact.im/p1/companies/COMPANY_ID/service_messages"
  -H "X-Private-Api-Token: YOUR_API_TOKEN"
  -d "phone=79250000001&short_text=hi&long_text=hello"

The above command returns JSON structured like this:

{
   "status":"ok",
   "data":{
     "id": 42,
     "company_id": 154
   }
}

HTTP Request

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

Query Parameters

Parameter Required Validations Description
phone true Must be in format 79250000001 Recipient phone number
short_message true Must be a String Short message text
long_message true Must be a String Long message text

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.