Qpien API Documentation

website·Indexed 35 days ago

https://qpien.apidog.io

Documentation for the Qpien API, providing tools to manage customer conversations, contacts, and communication channels. Includes guides on authentication, scope-based permissions, and sending messages via WhatsApp. Features modules for CustomerPersons, Conversations, Messages, and WhatsApp Business Templates, as well as support for real-time notifications via webhooks.

Tokens: 9.9K
Snippets: 54
Records: 61
Agent score: 46%

What's inside Qpien

ExternalMessage entity model

The ExternalMessage type represents a message exchanged within a conversation. It contains metadata about the sender, the conversation ID, the channel used (e.g., WhatsApp, Email), and the content of the message in both plain text and HTML formats. It also supports complex data types for emails, comments, questions, media attachments, and interactive elements like catalog messages and flow bot quick replies.

type ExternalMessage {
   _id: ID
   sender: senderData
   conversation: ID
   messageType: MessageType
   channelType: ChannelType
   senderType: SenderType
   content: String
   contentHtml: String
   subject: String
   emailData: EmailDataType
   commentData: CommentDataType
   questionData: QuestionDataType
   media: [Media]
   template_cards: Object
   product_cards: Object
   channelMessageId: String
   ackStatus: AckType
   createdAt: Date
   autoCreate: Boolean
   failedReason: FailedReasonType
   surveyData: surveyDataForLivechat
   informativeButtons: InformativeButtonsType
   flowBotQuickReplyResponseId: String
   flowBotQuickReplyButtonsRequired: Boolean
   flowBotQuickReply: [FlowBotQuickReplyType]
   quotedMessage: QuotedMessageType
   reactions: ReactionEnum
   frontMsgId: String
   listMessage: ListMessageType
   catalogMessage: CatalogInteractiveType
   catalogOrderData: CatalogOrderDataType
}

Set up Qpien webhooks for real-time notifications
Qpien webhooks allow your application to receive real-time notifications about platform events. To set one up, provide an HTTPS endpoint URL and subscribe to specific event types. Upon creation, Qpien generates an HMAC_SECRET that is displayed only once; this secret must be stored securely to verify incoming requests.
```
{
  "endpointUrl": "https://yourdomain.com/webhook",
  "events": ["NEW_INCOMING_MESSAGE", "JOIN_CONVERSATION"],
  "status": "ACTIVE",
  "secret": "9f8d1b91e23a4a0f8f4b1c8d7b2f19e1"
}
```
https://docs.qpien.com/custom-channel-2072678m0.mdwebsitellms
Generate an OAuth access token
To obtain an access token, use the generateOAuthToken mutation with your clientId and clientSecret. These credentials are generated in the Qpien App under Api Keys. Note that the Client Secret is only visible during creation.
```
curl -X POST https://api.qpien.com/api/v1 \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { generateOAuthToken(clientId: \"your_client_id\", clientSecret: \"your_client_secret\") { accessToken expiresIn } }"
  }'
```
https://docs.qpien.com/overview-1618762m0.mdwebsitellms
Authenticate requests to the Qpien API
All requests to the Qpien API must be authenticated using an access token. To authenticate, you must first obtain an access token by calling the generateOAuthToken GraphQL mutation using a Client ID and Client Secret generated in the Qpien App dashboard.
Once obtained, the access token must be included in the Authorization header of every API request. Tokens are valid for 1 hour. If you update the scopes (permissions) of your API key in the dashboard, you must generate a new access token for the changes to take effect.
```
# Example of using the token in a request
curl -X POST https://api.qpien.com/api/v1 \
  -H "Authorization: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ externalGetContacts { id firstName lastName ... } }"}'
```
https://docs.qpien.com/authentication-1619298m0.mdwebsitellms

Verify Qpien Webhook Signatures

To ensure a request originated from Qpien and prevent spoofing, verify the X-Qpien-Signature header. The signature is generated using HMAC SHA-256 of the raw JSON payload using your unique HMAC secret: HMAC_SHA256(secret, JSON.stringify(payload)).

import crypto from 'crypto';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const receivedSignature = req.headers['X-Qpien-Signature'];
  const payload = req.body;

  const expectedSignature = crypto
    .createHmac('sha256', process.env.HMAC_SECRET!)
    .update(JSON.stringify(payload))
    .digest('hex');

  if (receivedSignature === expectedSignature) {
    console.log('✅ Webhook verified');
    res.sendStatus(200);
  } else {
    console.log('❌ Invalid signature');
    res.sendStatus(401);
  }
});

app.listen(3000, () => console.log('Listening on port 3000'));

Fetch connected platforms via cURL

Example of how to request the list of all connected platforms using a cURL command. Replace YOUR_ACCESS_TOKEN with a valid authorization token.

curl --location 'https://api.qpien.com/api/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--data '{
  "query": "query ExternalGetAllConnectedPlatformList { externalGetAllConnectedPlatformList { success data { _id name status channelId channelType senderEmailAddress } code message } }"
}'

Authenticate requests to the Qpien API
The Qpien API uses Bearer Token authentication. All requests must include the access token in the Authorization header. Access tokens are valid for 1 hour and must be refreshed or requested again upon expiration.
```
Authorization: <access_token>
```
https://docs.qpien.com/overview-1618762m0.mdwebsitellms

Verify Qpien webhook signatures

To ensure a request originated from Qpien, verify the X-Qpien-Signature header. The signature is generated using HMAC SHA-256 of the JSON-stringified payload and your unique HMAC secret. Always verify signatures to prevent spoofing.

import crypto from 'crypto';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const receivedSignature = req.headers['X-Qpien-Signature'];
  const payload = req.body;

  const expectedSignature = crypto
    .createHmac('sha256', process.env.HMAC_SECRET!)
    .update(JSON.stringify(payload))
    .digest('hex');

  if (receivedSignature === expectedSignature) {
    console.log('✅ Webhook verified');
    res.sendStatus(200);
  } else {
    console.log('❌ Invalid signature');
    res.sendStatus(401);
  }
});

app.listen(3000, () => console.log('Listening on port 3000'));

Send a private reply to a public comment
To send a private reply to a public comment, use the externalCreateMessage mutation with msgType set to PRIVATE_REPLY. This updates the target public comment's commentData and creates a new message with the PRIVATE_REPLY type.
https://docs.qpien.com/messages-1621762m0.mdwebsitellms
Set up Qpien Custom Channel Webhooks
Webhooks allow your application to receive real-time notifications for platform events. To set one up, provide an HTTPS endpoint URL and subscribe to specific events in your Qpien account. Upon creation, Qpien generates an HMAC_SECRET that is displayed only once; this secret must be stored securely to verify incoming request signatures.
```
{
  "endpointUrl": "https://yourdomain.com/webhook",
  "events": ["NEW_INCOMING_MESSAGE", "JOIN_CONVERSATION"],
  "status": "ACTIVE"
}
```
https://docs.qpien.com/custom-channel-2073292m0.mdwebsitellms
Paginate list results in Qpien API
List queries (such as externalGetConversationList or externalGetMessageList) use cursor or offset-based pagination. The response includes docs (the array of entities), hasNextPage (boolean), and totalDocs (total count).
```
query {
  externalGetMessageList(input: { conversationId: "123", limit: 10, offset: 0 }) {
    success
    data {
      docs {
        _id
        content
      }
      hasNextPage
      totalDocs
    }
  }
}
```
https://docs.qpien.com/overview-1618762m0.mdwebsitellms

Verify Qpien Webhook signatures

To ensure a webhook request originated from Qpien, verify the X-Qpien-Signature header. The signature is generated using HMAC SHA-256 of the JSON stringified payload using your unique HMAC_SECRET as the key.

Formula: HMAC_SHA256(secret, JSON.stringify(payload))

import crypto from 'crypto';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const receivedSignature = req.headers['X-Qpien-Signature'];
  const payload = req.body;

  const expectedSignature = crypto
    .createHmac('sha256', process.env.HMAC_SECRET!)
    .update(JSON.stringify(payload))
    .digest('hex');

  if (receivedSignature === expectedSignature) {
    console.log('✅ Webhook verified');
    res.sendStatus(200);
  } else {
    console.log('❌ Invalid signature');
    res.sendStatus(401);
  }
});

app.listen(3000, () => console.log('Listening on port 3000'));