Everpro Chat Open API (1.0.0)

Welcome to Everpro Chat API!

Everpro Chat Open API contains specification for public api provided by Everpro for partners. It describes how to communications between your service and Everpro RESTful Web Service.

The diagram below describes the overview flow of the Everpro Chat Open API. Before accessing the API, partners need to register their account and generate the client secret and client key.

Swim Lane Diagram

The diagram below explains how the interaction flows between the Partner system and the Everpro system to send message with template. Partner can skip the Get Device List and Get Message Template List steps if they already know the device phone number and message template key that will be used to send message.

Limitation

• Rate limit: 1000 requests per minute per IP address
• Token will expire after 24 hours

To keep the partner's system synchronized with events occurring in Everpro Chat, partner can configure a callback URL in the Everpro Chat Dashboard page API/App Integration. Once configured, Everpro will send HTTP POST requests to partner's callback URL whenever when specific events occur. Currently, the supported events are:

• Broadcast delivery status
• First inbound message
• First reply by agent
• Conversation closed
• Inbound message
• Agent replies
• System event

Please refer to section Callback for more details about the callback data for each event.

Signature

To ensure the authenticity and integrity of callback requests, every callback includes an x-everpro-signature header. The signature is generated using the HMAC SHA256 algorithm with the raw request body and the partner's callback key. The callback key can be found in the Everpro Chat Dashboard page API/App Integration once the callback URL is configured.

Signature Formula:

HMAC_SHA256(raw_request_body, callback_key)

We strongly recommend validating the signature before processing any callback request. If the generated signature does not match the value received in the x-everpro-signature header, the request should be rejected.

Signature Validation Example (Golang)

func ValidateSignature(
payload []byte,
secretKey string,
receivedSignature string,
) bool {
    hash := hmac.New(sha256.New, []byte(secretKey))
    hash.Write(payload)

    expectedSignature := hex.EncodeToString(hash.Sum(nil))

    return hmac.Equal(
        []byte(expectedSignature),
        []byte(receivedSignature),
    )
}

Example Usage

func callbackHandler(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
    http.Error(w, "invalid request body", http.StatusBadRequest)
    return
}

signature := r.Header.Get("x-everpro-signature")

if !ValidateSignature(body, secretKey, signature) {
    http.Error(w, "invalid signature", http.StatusUnauthorized)
    return
}

// Process callback event

w.WriteHeader(http.StatusOK)
}

Data Encryption

The callback payload may contain personal data and other sensitive information. To protect this data during transmission and prevent unauthorized access, the callback payload is encrypted before being sent to partners. The encrypted payload uses AES-256-GCM, which provides both confidentiality and integrity protection. The partner is responsible for decrypting the payload using the encryption key. The encryption key can be found in the Everpro Chat Dashboard page API/App Integration once the callback URL is configured.

Callback Payload Structure

Each callback payload contains a set of standard fields that provide information about the callback event.

JSON
{
  "id": "<request id>",
  "user_id": "<user id>",
  "timestamp": "<timestamp>",
  "event": "<event name>",
  "data": {
    "room_id": "<room id>",
    "customer_phone_number": "<customer phone number>",
    "device_phone_number": "<device phone number>",
    ...
  },
  "encrypted_data": "<encrypted data>"
}

Standard Fields

Field	Type	Description
id	String	Unique identifier for the callback event.
user_id	String	Identifier of the user associated with the event.
timestamp	String	The timestamp when the event occurred, in ISO 8601 format.
event	String	The name of the callback event.
data	Object	The callback data in plain format. This field is deprecated and will be removed in the future.
encrypted_data	String	The callback data encrypted using AES-256-GCM.

Encrypted_data
The encrypted_data field contains the encrypted version of the callback data. After successfully decrypting the encrypted_data field, the resulting payload will follow the data structure defined for the corresponding event. Please refer to section Callback for more details about the callback data for each event. To support a smooth transition to encrypted callback data, the payload format will be introduced in two phases.

New Callback Events
For new callback events, only `encrypted_data` will be provided. Clients must decrypt and use `encrypted_data` to process these events.

JSON
{
  "id": "<request id>",
  "user_id": "<user id>",
  "timestamp": "<timestamp>",
  "event": "<event name>",
  "encrypted_data": "<encrypted data>"
}

Existing Callback Events
For existing callback events, both data and encrypted_data will initially be provided:

JSON
{
  "id": "<request id>",
  "user_id": "<user id>",
  "timestamp": "<timestamp>",
  "event": "<event name>",
  "data": {
    "room_id": "<room id>",
    "customer_phone_number": "<customer phone number>",
    "device_phone_number": "<device phone number>",
    ...
  },
  "encrypted_data": "<encrypted data>"
}

The plain `data` field will be temporarily maintained for backward compatibility to prevent disruption to existing client integrations. However, partners are expected to migrate to `encrypted_data` as soon as possible. After a transition period, the plain `data` field will no longer be included in callback payloads for existing events.

Data Decryption

The partner must decrypt the encrypted_data field using the AES-256-GCM encryption key provided by our system. The following example demonstrates how to decrypt the payload using Go:

package main

import (
  "crypto/aes"
  "crypto/cipher"
  "crypto/sha256"
  "encoding/base64"
  "errors"
)

// DecryptAES256GCM decrypts a value produced by EncryptAES256GCM.
func DecryptAES256GCM(encryptedData, encryptionKey string) ([]byte, error) {
  key := sha256.Sum256([]byte(encryptionKey))

  block, err := aes.NewCipher(key[:])
  if err != nil {
    return nil, err
  }

  gcm, err := cipher.NewGCM(block)
  if err != nil {
    return nil, err
  }

  data, err := base64.StdEncoding.DecodeString(encryptedData)
  if err != nil {
    return nil, err
  }

  nonceSize := gcm.NonceSize()
  if len(data) < nonceSize {
    return nil, errors.New("ciphertext too short")
  }

  nonce, cipherText := data[:nonceSize], data[nonceSize:]
  decryptedData, err := gcm.Open(nil, nonce, cipherText, nil)
  if err != nil {
    return nil, err
  }

  return decryptedData, nil
}

package main

import (
  "errors"
  "fmt"
)

func main() {
  encryptionKey := "<encryption key>"
  encryptedData := "<encrypted data>"

  // Decrypt
  decryptedData, err := DecryptAES256GCM(encryptedData, encryptionKey)
  if err != nil {
    return
  }

  fmt.Printf("Decrypted Data: %s", string(decryptedData))
}

Response Requirements

Your callback endpoint should return an HTTP 200 OK response after successfully processing the callback request.