With Papo (https://papo.global/), you can use the REST API to list conversations, send text messages, apply tags, and assign conversations to agents, automating customer service processes without accessing the interface. The API offers endpoints that mirror the functionalities of the Conversations module, allowing external systems to manage interactions programmatically.
| API Action | What it does | Example use |
|---|---|---|
| List conversations | Returns the account's conversations, with filters by status, tag, or agent | Monitor active or closed conversations from an external CRM |
| Send text message | Sends a text message to a contact (respecting WhatsApp's 24-hour window) | Notify a customer about an order update |
| Apply tag | Creates a tag (if it doesn't exist) and applies it to the contact and the open conversation | Mark conversations as “Urgent” or “Post-sale” automatically |
| Assign conversation | Assigns a contact's open conversations to a specific agent | Route leads to the salesperson responsible for the region |
How the Papo Conversations API works
The Papo API follows the REST standard, with authentication via secret key (Bearer token) and JSON responses. All operations described here use the same authentication base and can be combined to create automated workflows — for example, a triage system that, upon receiving a new lead, lists recent conversations, applies a “New” tag, and assigns it to the on-duty agent.
The API base is https://app.papo.global/api/v1. To use the conversations, tags, and assignment endpoints, you need an API token generated in the Papo panel. Complete documentation with specific endpoints and parameters is available at papo.global/pt/docs.
Step-by-step to use the API resources
1. Generate an API token
In the Papo panel, go to the developer or access tokens section. Create a secret key (sk_live_…) with the appropriate permissions to manage conversations. Store the token in a safe place — it will be sent in the Authorization header of all requests.
2. List conversations
Use the conversation listing endpoint to get the account's conversations. The request accepts filter parameters such as:
- Status: open, closed, or all conversations.
- Tag: filters by one or more applied tags.
- Agent: restricts to conversations assigned to a specific user.
- Period: date range to limit the query.
The response includes the conversation identifier, contact, channel, status, and last messages. With this data, you can monitor the volume of conversations or trigger conditional actions from an external system.
3. Send a text message
To send a text message to a contact, use the message sending endpoint. The request requires:
- Recipient number in international format (e.g.,
5511999999999). - Message text.
- Instance identifier (optional) — if your account has more than one WhatsApp connection, you can specify which one to use.
The API returns a confirmation that the request was accepted. Remember that sending text messages is subject to WhatsApp's 24-hour window; for communications outside this period, you must use pre-approved message templates (HSM).
4. Apply tags to contacts and conversations
The API allows you to manage tags in two ways:
- Create a tag in the account: define a title, color, and description for the new tag.
- Apply a tag: associate an existing tag with a contact and that contact's open conversation. If the tag doesn't exist yet, it will be created automatically during application.
This is useful for automatically classifying conversations based on your system's rules — for example, marking as “Complaint” when the customer sends a specific keyword.
5. Assign conversations to agents
With the assignment endpoint, you can assign an agent to all open conversations of a given contact. Just provide the contact identifier and the user/agent ID. The account's agent list can be obtained through the user listing endpoint, which returns the name, email, and ID of each team member.
This functionality is essential for automatic routing: a CRM system can, upon identifying the lead's profile, assign it to the correct salesperson without manual intervention.
Who should use the Conversations API
- Operations that already use external systems (ERP, CRM, e-commerce platforms) and want to integrate Papo's customer service without duplicating efforts.
- Support teams with complex routing rules, who need to classify and direct conversations automatically based on customer data.
- Developers building custom dashboards or triggering notifications from customer service events.
- White label resellers who manage multiple accounts and want to automate the configuration of tags and assignments for each client.
Frequently asked questions
Do I need an API token to use these endpoints?
Yes. All requests to the Papo API require authentication via secret key, sent in the Authorization: Bearer sk_live_… header. Tokens are generated in the account panel.
Does the API allow sending messages outside WhatsApp's 24-hour window?
Sending text messages via the API respects the 24-hour window. For proactive communications outside this period, you must use approved message templates (HSM). Papo offers specific endpoints for sending HSM.
Can I list conversations by tag?
Yes. The conversation listing endpoint accepts a tag filter, allowing you to retrieve only conversations marked with one or more specific tags.
How do I apply a tag to a contact via API?
Use the tags endpoint, providing the tag identifier (or the data for creation) and the contact identifier. The tag will be applied to the contact and the corresponding open conversation.
Does the API return the full conversation history?
The conversation listing returns metadata and the last messages. To get the full message history of a specific conversation, consult the API documentation, which details the message retrieval endpoints.
Is it possible to assign a conversation to an agent without knowing the user ID?
You can first list the account's users (agents endpoint) to get the IDs and then use the assignment endpoint. The agent list includes name and email, making identification easier.
Read also
- How to use the Papo API to manage your white label reseller clients
- How to use the Papo API to manage custom contact attributes
Test the API and all Papo modules at no cost — the first user is free and does not require a credit card.