Skip to Content
CallMitraDocs

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.

EndpointWhat 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}/activitiesPage through older activities
POST /api/v1/tickets/{ticket_id}/activitiesAdd a private team note
POST /api/v1/tickets/{ticket_id}/repliesReply to the customer on WhatsApp
GET /api/v1/tickets/categoriesList categories
GET /api/v1/tickets/teamsList teams

A key limited to resources needs Tickets (Authentication).

The ticket

FieldDescription
idTicket ID.
refShort reference shown to people, for example T-1A2B3C4D.
subject, descriptionOne-line summary and details.
statusopen, in_progress, waiting_on_customer, resolved or closed.
prioritylow, normal, high or urgent.
typesupport or sales_followup.
sourceHow it was opened: manual, inbound_call, outbound_call, import or whatsapp_conversation.
leadId, leadName, leadPhoneThe lead (customer) the ticket is about. Every ticket has one.
sourceCallIdThe call that opened the ticket, if any.
waConversationIdThe WhatsApp conversation it came from, if any.
categoryId, categoryNameThe category, or null.
teamId, teamNameThe team it is routed to, or null.
assigneesEveryone assigned (userId, name, email), in assignment order.
assignedToUserIdThe first assignee's user ID, or null when unassigned.
tagsTags.
dueAt, overdueResolution due time, and whether it has passed without the ticket being resolved.
slaService-level targets: firstResponse, resolution and paused.
createdAt, updatedAt, resolvedAt, closedAtTimestamps (ISO 8601).
mergedIntoIdSet when the ticket was merged into another. A merged ticket is read-only.
versionGoes 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 parameterDescription
page, limitPage number from 1, and tickets per page (1–200).
searchTicket ref, words in the subject or description, or the lead's name or phone.
statusOne status. open also matches in_progress and waiting_on_customer.
prioritylow, normal, high or urgent.
typesupport or sales_followup.
leadIdOnly this lead's tickets.
sourceCallIdOnly tickets opened from this call.
categoryIdCategory ID, or none for tickets without one.
teamIdTeam ID, or none for tickets without one.
tagOnly tickets with this tag.
unassignedtrue for tickets nobody is assigned to.
sortupdated (the default), created, due, priority or status.
dirasc 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.

FieldDescription
subjectRequired. One-line summary, 1–512 characters.
descriptionDetails, up to 20,000 characters.
leadIdThe lead the ticket is about.
waConversationIdA WhatsApp conversation, instead of leadId.
typesupport (the default) or sales_followup.
prioritylow, normal, high or urgent. Default: the category's priority, else normal.
categoryIdA category ID from List categories.
tagsUp to 20 tags.
assignedToUserIdAssign one team member (user ID).
assignedUserIdsAssign several team members (up to 50). Wins over assignedToUserId.
sourceCallIdThe call the ticket came from.
dueAtResolution 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:

FieldDescription
subject, descriptionText fields.
statusopen, in_progress, waiting_on_customer, resolved or closed.
prioritylow, normal, high or urgent.
typesupport or sales_followup.
dueAtResolution due time (ISO 8601).
categoryIdCategory ID. null clears it.
teamIdTeam ID. null takes the ticket out of its team.
tagsReplaces all tags (up to 20).
versionThe 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 403 ticket_edit_forbidden.
  • Reopening a closed ticket needs a manager's key. Otherwise it fails with 403 ticket_reopen_forbidden.
  • A merged ticket is read-only: changes fail with 409 ticket_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:

NoteReply
EndpointPOST .../activitiesPOST .../replies
Who sees itYour team onlyThe customer, on WhatsApp
activityTypecommentreply
Retry safetyIdempotency-Key headerclientId 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.

FieldDescription
clientIdRequired. 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.
textReply text, up to 4096 characters. Only within 24 hours of the customer's last message.
templateEventOutside 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.
versionThe 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.codeReason
replies_offCustomer replies are turned off in Tickets → Settings.
no_numberNo WhatsApp number to reply from.
number_offlineThe WhatsApp number is not connected.
no_phoneThe lead has no valid phone number.
dncThe customer is on do-not-contact.
opted_outThe customer opted out of WhatsApp messages.
window_closedThe 24-hour window is closed. Send templateEvent instead of text.

Categories and teams

  • GET /api/v1/tickets/categories lists categories in display order. Each has id, name, isActive, sortOrder, defaultPriority and defaultTeamId. Inactive categories are included unless you send includeInactive=false.
  • GET /api/v1/tickets/teams lists teams by name. Each has id, name, isDefault, members and assignmentMode (manual, round_robin or least_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:

EventWhen
ticket.createdA ticket was opened.
ticket.updatedA ticket changed.
ticket.resolvedA ticket was resolved.
ticket.reopenedA ticket was opened again.
ticket.ratedA customer rated a ticket.

See Webhook events for the payloads.

Errors

StatusCodeWhen
403ticket_edit_forbiddenThe key's user is an agent and the ticket is assigned to someone else.
403ticket_reopen_forbiddenReopening a closed ticket without a manager's key.
404resource_not_foundThe ticket, lead or conversation does not exist in your workspace.
409ticket_version_conflictThe ticket changed since the version you sent. Fetch it again and retry.
409ticket_mergedThe ticket was merged into another and is read-only.
409ticket_reply_blockedThe reply cannot be sent; see detail.code.
409ticket_attachment_unavailableOne of the attachmentIds was already used or removed. Attachments are uploaded in the console; API integrations normally leave attachmentIds out.
409idempotency_key_reusedSame Idempotency-Key, different body.
422parameter_invalidA field is missing or invalid.

Every error uses the standard error envelope.

On this page