Update satisfaction survey order
/v1/satisfaction/orderorg.permission.satisfaction.updateorg.admin.satisfaction.writeThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Updates the display order of satisfaction surveys for the organization.
The satisfactionForms array may contain up to 500 survey IDs and defines the order in which enabled surveys are evaluated for a channel.
Satisfaction surveys
Satisfaction surveys (CSAT) ask customers to rate their experience after a conversation. A survey defines the question, rating scale, channel and audience; each time one is sent, Kustomer creates a satisfaction response that tracks delivery and stores the customer's rating and comments.
CSAT measures how customers feel about the help they got. Admins build surveys in the Kustomer admin settings; customers answer them in the chat widget or in a message on email, SMS and other channels; agents and managers see the results on the conversation and in reporting. The API splits this into two objects: the survey (type satisfaction), which is configuration, and the satisfaction response (type satisfaction_response), which is one survey sent to one customer about one conversation.
Surveys
Key survey fields:
channel: where the survey is sent, such asemail,sms,chat,voice,facebookorwhatsapp.frompicks the sending account for that channel.formType: alwayscsat.scale.options: how many rating choices the customer sees,2,3,5or10, with optionallabelLowandlabelHigh.introductionandratingPrompt: the text around the rating question.questionsadds follow-up questions, each either a free-textresponseor apropertyquestion tied to a conversation attribute named inproperty.delayTime: how long after the conversation closes to send the survey, in milliseconds. Chat surveys are offered right away.criteria: audience rules in the sameand/orformat as queue rules. Omit it on update to keep the current rules; sendnullor empty lists to clear them.
Each channel can have up to 30 enabled surveys, and creating or enabling one beyond that returns 422. Disabled surveys don't count.
Which survey a conversation gets
When a conversation is marked done, or a chat ends, Kustomer looks at the enabled surveys for the channel of the conversation's latest message and keeps those whose criteria match. If several match, the one with the most criteria rules wins, and the survey order breaks ties. If the conversation is reopened before a scheduled survey goes out, the survey is canceled.
Responses
status |
Meaning |
|---|---|
scheduled |
Created and waiting for scheduledFor. |
offered |
Sent to the customer (sentAt). |
rated |
The customer gave a rating. |
commented |
The customer also left a comment or answered follow-up questions. |
unresponded |
No answer was received. |
canceled |
Not sent, for example because the conversation reopened. |
rating is the customer's raw choice on the survey's scale, and score is the derived result used for CSAT reporting, 1 for a satisfied rating and 0 otherwise. answers holds follow-up answers, and responses stop accepting changes after lockedAt. Each response links to its satisfaction survey, customer and conversation.
Which endpoint to use
| To | Call |
|---|---|
| List the org's surveys | GET /v1/satisfaction |
| Create a survey | POST /v1/satisfaction |
| Change, enable or disable a survey | PUT /v1/satisfaction/{id} |
| Set the survey order used to break ties | PUT /v1/satisfaction/order |
| Read one customer's response and rating | GET /v1/satisfaction-responses/{id} |
To find responses in bulk, search conversations by the conversation_satisfaction_* attributes, such as rating, score or status. If you run your own chat UI, record a rating with the chat satisfaction response endpoint. PUT /v1/satisfaction/order takes the full ordered list of survey IDs in satisfactionForms, up to 500.
Request body
application/jsonrequiredOrdered list of satisfaction survey IDs.
Responses
OK