Tickets
Create, update and follow support tickets, add team notes, and reply to customers on WhatsApp.
Tickets track customer requests in CallMitra's helpdesk. Your agents and your team open them in calls, WhatsApp chats and the console. With the API you can create tickets from your own systems, keep them in sync, add notes and reply to the customer.
| Endpoint | What it does |
|---|---|
GET /api/v1/tickets/ | List and filter tickets |
POST /api/v1/tickets/ | Create a ticket |
GET /api/v1/tickets/{ticket_id} | Get a ticket with its latest activities |
PATCH /api/v1/tickets/{ticket_id} | Update a ticket |
GET /api/v1/tickets/{ticket_id}/activities | Page through older activities |
POST /api/v1/tickets/{ticket_id}/activities | Add a private team note |
POST /api/v1/tickets/{ticket_id}/replies | Reply to the customer on WhatsApp |
GET /api/v1/tickets/categories | List categories |
GET /api/v1/tickets/teams | List teams |
A key limited to resources needs Tickets (Authentication).
The ticket
| Field | Description |
|---|---|
id | Ticket ID. |
ref | Short reference shown to people, for example T-1A2B3C4D. |
subject, description | One-line summary and details. |
status | open, in_progress, waiting_on_customer, resolved or closed. |
priority | low, normal, high or urgent. |
type | support or sales_followup. |
source | How it was opened: manual, inbound_call, outbound_call, import or whatsapp_conversation. |
leadId, leadName, leadPhone | The lead (customer) the ticket is about. Every ticket has one. |
sourceCallId | The call that opened the ticket, if any. |
waConversationId | The WhatsApp conversation it came from, if any. |
categoryId, categoryName | The category, or null. |
teamId, teamName | The team it is routed to, or null. |
assignees | Everyone assigned (userId, name, email), in assignment order. |
assignedToUserId | The first assignee's user ID, or null when unassigned. |
tags | Tags. |
dueAt, overdue | Resolution due time, and whether it has passed without the ticket being resolved. |
sla | Service-level targets: firstResponse, resolution and paused. |
createdAt, updatedAt, resolvedAt, closedAt | Timestamps (ISO 8601). |
mergedIntoId | Set when the ticket was merged into another. A merged ticket is read-only. |
version | Goes up on every change. Send it back to avoid overwriting someone else's change. |
A single ticket (get, and the ticket in update responses) also has canEdit, canManageAssignees and canReopenClosed: what the key's user may do with it.
List tickets
The list is sorted by last change, newest first. It is paged with page and limit (default 25, up to 200). See Pagination.
| Query parameter | Description |
|---|---|
page, limit | Page number from 1, and tickets per page (1–200). |
search | Ticket ref, words in the subject or description, or the lead's name or phone. |
status | One status. open also matches in_progress and waiting_on_customer. |
priority | low, normal, high or urgent. |
type | support or sales_followup. |
leadId | Only this lead's tickets. |
sourceCallId | Only tickets opened from this call. |
categoryId | Category ID, or none for tickets without one. |
teamId | Team ID, or none for tickets without one. |
tag | Only tickets with this tag. |
unassigned | true for tickets nobody is assigned to. |
sort | updated (the default), created, due, priority or status. |
dir | asc or desc. |
curl "https://api.callmitra.ai/api/v1/tickets/?status=open&priority=urgent&limit=50" \
-H "X-API-Key: $CALLMITRA_API_KEY"{
"success": true,
"tickets": [
{
"id": "a1b2c3d4-0000-4000-8000-000000000001",
"ref": "T-A1B2C3D4",
"subject": "Refund not received",
"status": "open",
"priority": "urgent",
"type": "support",
"leadId": "5e6f7a8b-0000-4000-8000-000000000002",
"leadName": "Asha Verma",
"leadPhone": "+919812345678",
"teamId": null,
"assignees": [],
"version": 3
}
],
"pagination": {
"currentPage": 1,
"itemsPerPage": 50,
"totalItems": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false,
"totalCapped": false
},
"sort": { "key": "updated", "dir": "desc" }
}The ticket above is shortened. totalCapped is true when totalItems stopped counting at the cap.
Create a ticket
Every ticket belongs to a lead. Send leadId, or waConversationId to open the ticket from a WhatsApp conversation (its contact's lead is used and source becomes whatsapp_conversation). If you send both, they must point to the same lead. Sending neither fails with 422 parameter_invalid.
| Field | Description |
|---|---|
subject | Required. One-line summary, 1–512 characters. |
description | Details, up to 20,000 characters. |
leadId | The lead the ticket is about. |
waConversationId | A WhatsApp conversation, instead of leadId. |
type | support (the default) or sales_followup. |
priority | low, normal, high or urgent. Default: the category's priority, else normal. |
categoryId | A category ID from List categories. |
tags | Up to 20 tags. |
assignedToUserId | Assign one team member (user ID). |
assignedUserIds | Assign several team members (up to 50). Wins over assignedToUserId. |
sourceCallId | The call the ticket came from. |
dueAt | Resolution due time (ISO 8601). |
The category and the source decide the ticket's team. The team's rules may then assign it automatically. Send an Idempotency-Key header so a retry does not create a second ticket (Idempotency).
curl -X POST https://api.callmitra.ai/api/v1/tickets/ \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Idempotency-Key: crm-case-88213" \
-H "Content-Type: application/json" \
-d '{
"leadId": "5e6f7a8b-0000-4000-8000-000000000002",
"subject": "Refund not received",
"description": "Order #1042, refund started on 10 Jan.",
"priority": "high",
"tags": ["refund"]
}'The response is {"success": true, "ticket": {...}}, the same as Get a ticket.
Get a ticket
GET /api/v1/tickets/{ticket_id} returns the ticket with its latest activities, oldest first. When hasOlderActivities is true, pass activitiesCursor as before to GET /api/v1/tickets/{ticket_id}/activities to read older ones (limit default 50, up to 200). Each page returns the next activitiesCursor; stop when hasOlderActivities is false.
Each activity has id, ticketId, activityType, actorUserId (null for the customer or the system), actorName, createdAt and payload. Common activityType values are created, comment (a note, its text in payload.note), reply, status_change and assignment.
Update a ticket
PATCH /api/v1/tickets/{ticket_id} changes only the fields you send:
| Field | Description |
|---|---|
subject, description | Text fields. |
status | open, in_progress, waiting_on_customer, resolved or closed. |
priority | low, normal, high or urgent. |
type | support or sales_followup. |
dueAt | Resolution due time (ISO 8601). |
categoryId | Category ID. null clears it. |
teamId | Team ID. null takes the ticket out of its team. |
tags | Replaces all tags (up to 20). |
version | The version you last read. If the ticket changed since, the request fails with 409 ticket_version_conflict. Leave it out to skip the check. |
Assignees can be set when you create a ticket. The update endpoint does not change them.
curl -X PATCH https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001 \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "resolved", "version": 3 }'The response holds ticket (the ticket after the change), changed (the fields that changed) and activities (only the activities this request added).
Who may change what:
- The key acts as the user who created it. If that user is an agent, it can change only tickets assigned to it or unassigned ones. Others fail with
403ticket_edit_forbidden. - Reopening a
closedticket needs a manager's key. Otherwise it fails with403ticket_reopen_forbidden. - A merged ticket is read-only: changes fail with
409ticket_merged. Update the ticket it was merged into.
If your workspace set up ticket updates in the console (Tickets → Settings), a status change can also send the customer a WhatsApp update.
Notes and replies
There are two ways to write on a ticket:
| Note | Reply | |
|---|---|---|
| Endpoint | POST .../activities | POST .../replies |
| Who sees it | Your team only | The customer, on WhatsApp |
activityType | comment | reply |
| Retry safety | Idempotency-Key header | clientId in the body |
Add a note
Send note (up to 8000 characters). You can also send status to move the ticket in the same request, and version for the conflict check.
curl -X POST https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001/activities \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Idempotency-Key: crm-note-5521" \
-H "Content-Type: application/json" \
-d '{ "note": "Finance confirmed the refund on 14 Jan.", "status": "waiting_on_customer" }'An empty note fails with 422 parameter_invalid.
Reply to the customer
A reply goes to the ticket's customer on WhatsApp. It is sent from the number of the ticket's WhatsApp chat, or else from the ticket-updates number chosen in Tickets → Settings. Replies are off until a manager turns them on there.
| Field | Description |
|---|---|
clientId | Required. Your unique ID for this reply, 8–64 characters. A retry with the same clientId returns the first reply, with replayed: true, and never sends twice. |
text | Reply text, up to 4096 characters. Only within 24 hours of the customer's last message. |
templateEvent | Outside the window: the ticket event whose approved template to send, for example waiting_on_customer. Events are created, in_progress, waiting_on_customer, resolved, resolved_rating and closed; the template must be set up for that event in Tickets → Settings. Cannot be combined with text. |
version | The ticket version you last read (optional). |
curl -X POST https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001/replies \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "clientId": "crm-reply-5522", "text": "Your refund is on its way." }'The reply is queued for sending and recorded on the ticket right away. When it cannot be sent, nothing is sent and the request fails with 409 ticket_reply_blocked. detail.code says why:
detail.code | Reason |
|---|---|
replies_off | Customer replies are turned off in Tickets → Settings. |
no_number | No WhatsApp number to reply from. |
number_offline | The WhatsApp number is not connected. |
no_phone | The lead has no valid phone number. |
dnc | The customer is on do-not-contact. |
opted_out | The customer opted out of WhatsApp messages. |
window_closed | The 24-hour window is closed. Send templateEvent instead of text. |
Categories and teams
GET /api/v1/tickets/categorieslists categories in display order. Each hasid,name,isActive,sortOrder,defaultPriorityanddefaultTeamId. Inactive categories are included unless you sendincludeInactive=false.GET /api/v1/tickets/teamslists teams by name. Each hasid,name,isDefault,membersandassignmentMode(manual,round_robinorleast_busy).
A new ticket goes to its category's defaultTeamId. When neither its category nor its source picks a team, it goes to the team with isDefault: true. Categories and teams are managed in the console.
Webhooks
Get ticket changes pushed to you instead of polling:
| Event | When |
|---|---|
ticket.created | A ticket was opened. |
ticket.updated | A ticket changed. |
ticket.resolved | A ticket was resolved. |
ticket.reopened | A ticket was opened again. |
ticket.rated | A customer rated a ticket. |
See Webhook events for the payloads.
Errors
| Status | Code | When |
|---|---|---|
403 | ticket_edit_forbidden | The key's user is an agent and the ticket is assigned to someone else. |
403 | ticket_reopen_forbidden | Reopening a closed ticket without a manager's key. |
404 | resource_not_found | The ticket, lead or conversation does not exist in your workspace. |
409 | ticket_version_conflict | The ticket changed since the version you sent. Fetch it again and retry. |
409 | ticket_merged | The ticket was merged into another and is read-only. |
409 | ticket_reply_blocked | The reply cannot be sent; see detail.code. |
409 | ticket_attachment_unavailable | One of the attachmentIds was already used or removed. Attachments are uploaded in the console; API integrations normally leave attachmentIds out. |
409 | idempotency_key_reused | Same Idempotency-Key, different body. |
422 | parameter_invalid | A field is missing or invalid. |
Every error uses the standard error envelope.