Introduction

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

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

5 easy steps for integration:

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

Options for using our service

1. Curl

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

2. SDK-PHP

You could use our SDK-PHP

Private API V1

Authentication

All requests to Pact API must be authenticated.

There are two options for autentication:

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

X-Private-Api-Token: YOUR_API_TOKEN

or as a additional parameter in URI

"API_ENDPOINT_HERE?private_api_token=YOUR_API_TOKEN"

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

Examples

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

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

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

Companies

Get All Companies

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

<?php

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

// Get companies without params

$client->companies->getCompanies();

// Get companies with params

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

The above command returns JSON structured like this:

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

This endpoint return list of all user companies.

HTTP Request

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

Query Parameters

Update company

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint updates specific company attributes.

HTTP Request

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

URL Parameters

Query Parameters

Create new company

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint creates a new company for user.

HTTP Request

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

Query Parameters

Channels

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

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

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

Get All channels

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint returns all the company channels.

HTTP Request

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

Query Parameters

URL Parameters

Create new channel

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

Create channel:

<?php

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

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

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

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

Create whatsapp channel:

<?php

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

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

Create instagram business channel:

<?php

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

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

Create facebook/vkontakte/vkontakte_direct/telegram/viber channel

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint create a new channel in the company.

HTTP Request

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

URL Parameters

Query Parameters

Create whatsapp channel

Create whatsapp business channel (dialog360 by token)

Create whatsapp business channel (dialog360 by channel_id)

Create avito channel

Create instagram business channel

Steps:

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

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

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

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

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

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

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

Create facebook/vkontakte/vkontakte_direct/telegram/viber channel

Create telegram personal channel (by qr code)

Create telegram personal channel (by digital code)

Request code Confirm code

Get token for vk group:

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

Update channel

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

Update channel:

<?php

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

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

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

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

Update instagram channel:

<?php

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

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

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint updates existing channel in the company.

HTTP Request

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

URL Parameters

Query Parameters

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

Delete channel

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

Delete channel:

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

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

The above command returns JSON structured like this:

{
   "status":"deleted"
}

HTTP Request

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

URL Parameters

How to write first message to Whatsapp

Send first message to whatsapp

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

<?php

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

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

The above command returns JSON structured like this:

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

How to check if user has Whatsapp account

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

The above command returns JSON structured like this:

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

How to write first message to Whatsapp Business

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

<?php

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

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

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

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

You can also poll delivery status here: Jobs

HTTP Request

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

URL Parameters

Query Parameters

Whatsapp Business Template Parameters

Request code (whatsapp)

Request code:

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

<?php

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

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Query Parameters

Request challenge code

Request code (telegram personal)

Request code:

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

<?php

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

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

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

The above command returns JSON structured like this:

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

This endpoint request code for telegram personal

HTTP Request

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

URL Parameters

Query Parameters

Request challenge code

Confirm code (telegram personal)

Confirmation type is code

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

<?php

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

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

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

Successful response:

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

Confirmirmation type is password

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

<?php

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

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Query Parameters

Confirmation type is code

Confirmation type is password

Request code (instagram only)

Request challenge code:

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

<?php

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

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

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

The above command returns JSON structured like this:

{
  "result": "ok"
}

Request two factor authentication code:

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

<?php

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

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

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

The above command returns JSON structured like this:

{
  "result": "ok"
}

This endpoint request challenge or two factor authentication code.

HTTP Request

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

URL Parameters

Query Parameters

Request challenge code

Request two factor SMS authentication code

Confirm code (instagram only)

Confirm challenge code:

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

<?php

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

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

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

The above command returns JSON structured like this.

Successful response:

{
  "result": "ok"
}

Two factor authentication required:

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

Challenge required:

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

Confirm two factor authentication code:

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

<?php

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

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

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

The above command returns JSON structured like this:

{
  "result": "ok"
}

This endpoint submit challenge or two factor authentication code.

HTTP Request

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

URL Parameters

Query Parameters

challenge code

two factor authentication code

Conversations

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

Get All Conversations

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

<?php

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

// Get conversations:

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

// Get conversations with parameters:

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Query Parameters

URL Parameters

Create new conversation

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

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

<?php

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

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

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

The above command returns JSON structured like this:

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

         }
      }
   }
}

This endpoint creates conversation in the company using whatsapp channel.

Create first message for whatsapp business provider

HTTP Request

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

URL Parameters

Query Parameters for whatsapp channel

Query Parameters for telegram_personal channel

Update note for conversation

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

The above command returns JSON structured like this:

{
   "status":"updated"
}

This endpoint update note of conversation in the company.

HTTP Request

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

URL Parameters

Body Parameters

Get conversation details

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

<?php

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

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

The above command returns JSON structured like this:

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

         }
      }
   }
}

HTTP Request

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

URL Parameters

Update assignee for conversation

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

<?php

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Query Parameters

Toggle bitrix block openlines

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Query Parameters

Upload attachment for message

The above command returns JSON structured like this:

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

URL Parameters

Query Parameters

HTTP Request

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

Code example

<?php

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

// Example with file on local:

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

// Example with file url:

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

// Example with both variants:

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

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

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

Messages

Each message belongs to conversation. Message fields:

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

Get conversation messages

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

<?php

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Query Parameters

URL Parameters

Send message

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint delivers message to the client under specified conversation.

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

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

You can check operation result manually here: Jobs

HTTP Request

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

URL Parameters

Body Parameters

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

Interactive WABA message with buttons example

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

Upload attachments

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

<?php

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

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Query Parameters

Waba templates

A company with a whatsapp_business channel can have waba templates

Get waba templates

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

<?php

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

# Simple request

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

# Pagination

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

returns JSON structured like this:

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

HTTP Request

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

Query Parameters

URL Parameters

Webhooks

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

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

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

New conversation

The above command returns JSON structured like this:

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

When

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

Update conversation

The above command returns JSON structured like this:

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

When

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

New message

The above command returns JSON structured like this:

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

When

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

Message delivery/read status

The above command returns JSON structured like this:

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

When

• Message was delivered
• Message was read

Possible statuses:

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

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

Delivery job executed

The above command returns JSON structured like this:

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

When

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

Possible results:

• DELIVERED
• NOT DELIVERED

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

Whatsapp: new QR-code

The above command returns JSON structured like this:

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

When

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

Whatsapp: channel connected sucessfuly

The above command returns JSON structured like this:

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

When

QR-code was scanned successfuly

Whatsapp: phone offline

The above command returns JSON structured like this:

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

When

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

Whatsapp: phone online

The above command returns JSON structured like this:

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

When

Device with WhatsApp application is reachable again.

Whatsapp: channel not available

The above command returns JSON structured like this:

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

When

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

Whatsapp: channel disabled

The above command returns JSON structured like this:

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

When

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

Whatsapp: trying to resume channel work

The above command returns JSON structured like this:

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

When

We’re trying to resume work after previous conflict state

Whatsapp: synchronization completed

The above command returns JSON structured like this:

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

When

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

Instagram: changed state to disabled

The above command returns JSON structured like this:

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

When

• Service message successfully delivered
• Service message delivery failed

Group chats: new conversation

The above command returns JSON structured like this:

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

When

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

Group chats: new group message

The above command returns JSON structured like this:

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

When

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

Group chats: message delivery/read status

The above command returns JSON structured like this:

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

When

• Message was delivered
• Message was read

Possible statuses:

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

Group chats: new active member

The above command returns JSON structured like this:

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

When

• Group chat member sent new message first time.

Message delivery Jobs

Get Job details

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

<?php

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

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

The above command returns JSON structured like this:

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

This endpoint returns information about message delivery job

HTTP Request

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

URL Parameters

Message may be DELIVERED of NOT DELIVERED.

Message will be NOT DELIVERED if case when:

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

Private API V2

Authentication

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:

Terms and conditions

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

Legal

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

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

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