Work a ticket from open to closed

At the end of this guide you can create a ticket, hand it to a teammate, answer it and close it, from the dashboard or the API.

What you need first

• A workspace on a paid plan with at least one address whose purpose is ticket. The inbox guide explains address purposes.
• For the API requests: an API token with the write ability. A read token can run only the GET requests.
• Your workspace id, from GET /workspaces.

The fields that move a ticket

Status

Priority

One of low, medium or high. A ticket always has one, and an SLA policy is set per priority.

Waiting on

Separate from status, waiting_on says who owes the next message: us when the customer wrote last, customer when you replied, or null when nobody does (a closed ticket, for example). PimiDesk sets it as mail comes and goes. Notes and drafts do not change it.

Steps

1. Create the ticket. Most tickets create themselves: mail sent to a ticket address becomes one. To open one yourself, create it from the Tickets page in the dashboard or send:

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "subject": "Refund for a duplicate charge",
       "description": "Charged twice for my March invoice.",
       "priority": "high",
       "contact": { "name": "Maya Ross", "email": "[email protected]" },
       "workspace_email": "[email protected]"
     }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets

   subject, description and priority are required, plus either contact_id or a contact with a name and an email address. workspace_email picks which of your ticket addresses the ticket uses.

2. Assign it and set where it stands. agent_id is a member's user id; send null to unassign.

   curl -X PUT \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "status": "in_progress", "priority": "medium", "agent_id": 12 }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID

3. Tag it. Send tag_name to use a tag by name, or tag_id for one you already know. Tags are shared by tickets and both inboxes; a workspace holds up to 100.

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "tag_name": "billing" }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/tags

4. Save a draft. You have one draft per ticket. Saving again replaces it. Your teammates see that a draft exists on the ticket, so two people do not answer the same customer.

   curl -X PUT \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "message": "Hi Maya, I can see both charges. Refunding the second one now." }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/draft

5. Reply. A message of type email goes to the customer and replaces your saved draft. Write only the new text: the quoted history is added for you. A message is at most 10,000 characters, with up to 10 files.

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "type": "email", "message": "Hi Maya, the second charge is refunded." }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/messages

6. Leave a note for a teammate. A message of type internal_note is never sent to the customer. Each member in mentioned_user_ids is told by email.

   curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "internal_note",
       "message": "Refunded in the payment dashboard. Can you check the invoice?",
       "mentioned_user_ids": [12]
     }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/messages

7. Write the summary. A ticket carries one short Markdown summary, at most 1,000 characters. Its first line is the headline. When a new message arrives the summary is marked stale until someone writes it again.

   curl -X PUT \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Duplicate charge on the March invoice\n\nSecond charge refunded. Waiting for Maya to confirm." }' \
     https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/summary

8. Close it. Send { "status": "closed" } to the same PUT request as step 2.

Canned responses

A canned response is a saved reply any member can insert into the reply box. A workspace holds up to 100.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund sent",
    "content": "Hi {{contact.name}}, your refund for ticket {{ticket.id}} is on its way."
  }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/canned-responses

The text can hold 9 placeholders. The dashboard fills them in when you insert the response, and an automation fills them in when it sends one. A placeholder with no value is left empty.

• {{contact.name}}
• {{contact.email}}
• {{ticket.id}}
• {{ticket.subject}}
• {{conversation.id}}
• {{conversation.subject}}
• {{agent.name}}
• {{agent.email}}
• {{workspace.name}}

Bulk actions

Select tickets in a list, or send up to 100 ids with one of 15 actions:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [101, 102, 103], "action": "assign", "agent_id": 12 }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/bulk

Check that it worked

Open the ticket in the dashboard, or read its activity log. Changes to the ticket are listed there:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/tickets/TICKET_ID/activities

What goes wrong

Next

• Shared inbox and personal inbox: mail that is not a support ticket
• Automations: tag, assign and answer new tickets by rule
• SLA policies: response and resolution targets per priority
• API reference: every ticket endpoint and field