NAV
shell

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

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"

Companies

Get All Companies

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

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

This endpoint return list of all user companies.

HTTP Request

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

Update company

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

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

Create new company

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

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

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"

The above command returns JSON structured like this:

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

This endpoint returns all the company channels.

HTTP Request

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

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"

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
provider true Must be whatsapp

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

Create facebook/vkontakte/telegram/viber channel

Parameter Required Validations Description
provider true Must be one of: facebook, vkontakte, telegram, viber Shows which provider you want to connect
token true Must be a String Token for auth.

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"

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 passowrd. We don’t save password, only authorization cookies

For facebook/vkontakte/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"

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

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

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 true Must be String Message text

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"

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",
            "avatar":"/avatars/original/missing.png",
            "sender_external_id":"79260000001",
            "meta":{

            }
         }
      ]
   }
}

HTTP Request

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

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"

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",
         "avatar":"/avatars/original/missing.png",
         "sender_external_id":"79250000001",
         "meta":{

         }
      }
   }
}

This endpoint creates conversation in the company using whatsapp channel.

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

Get conversation details

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

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

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"

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",
            "attachments":[

            ]
         }
      ]
   }
}

HTTP Request

GET 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

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"

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

Query Parameters

Parameter Required Validations Description
message true Must be String Message text
attachments_ids false Must be an Array with attachments ids IDs of previously uploaded attachments.

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"

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 true Must be a File Attachment file

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.

New conversation

The above command returns JSON structured like this:

{
   "type":"conversation",
   "event":"new",
   "data":{
      "external_id":1,
      "name":"Sender Name",
      "channel_id":1,
      "channel_type":"whatsapp",
      "created_at":"2017-11-11 12:45:53 UTC",
      "last_message_at":null,
      "last_income_message_at":null
   }
}

When

New message

The above command returns JSON structured like this:

{
   "type":"message",
   "event":"new",
   "data":{
      "external_id":1,
      "channel_id":1,
      "channel_type":"whatsapp",
      "channel":{
        "id": 1,
        "type": "whatsapp"
      },
      "conversation_id":1,
      "message":"Message body",
      "income":true,
      "created_at":"2017-11-11 12:45:53 UTC",
      "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",
      "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",
      "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 offline",
      "date":"2017-11-11 12:45:53 UTC",
      "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",
      "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",
      "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",
      "details":{
         "entity":"channel",
         "entity_id":1
      }
   }
}

When

Message delivery Jobs

Get Job details

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

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:

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.