Which settings can you change?
Both endpoints take the same fields, and text values are trimmed before they’re saved.
| Field | Accepts | What it controls |
|---|---|---|
| productName | Text, 1 to 80 characters | The product the agent represents |
| agentName | Text, 1 to 60 characters | The name the agent uses |
| greeting | Text, up to 500 characters | What the agent says first |
| instructions | Text, up to 4,000 characters | How the agent behaves. The server adds its own rules around them, such as telling callers it’s an AI. |
| voice | marin or cedar, in lower case | One of the two voices |
| widgetLabel | Text, up to 30 characters | The button label |
| accentColor | A six-digit hex colour, such as #1f6feb | The button colour |
| allowedOrigins | Up to 10 origins | The websites that can start calls. Replaces the saved list. |
| enabled | true or false | Whether customer calls are accepted |
| agentConfigured | true or false | Marks the agent as set up for the dashboard’s checklist. The dashboard sets it when you save there. |
| escalationEnabled | true or false | Human handover for this agent, an early release. It can be turned on once a team phone number is verified for the agent, as explained below. |
| humanNumber | Leave it out | The team phone number for handover. Numbers are verified and changed only in the dashboard, so sending one returns 403 with “Verify and change your team number in Settings.” |
How are updates merged?
The server reads the agent’s saved settings, applies the fields you sent and saves the result only if nothing else changed the settings in between. If another change keeps landing first, it retries a few times and then returns 409 with “Settings changed at the same time. Try again.” Sending the same request again is safe.
- Fields you leave out keep their saved values.
- allowedOrigins isn’t merged: the list you send replaces the saved one, so include every origin you want to keep.
- An unknown field returns 400 with its name, such as “Unknown setting: greting”, so a typo never fails silently.
- The response is the agent’s full saved settings, which you can keep as your new baseline.
curl -X PATCH 'https://app.kawlnow.com/api/manage/sales-settings' \
-H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"greeting": "Hi, I can answer questions about plans and features. What are you looking for?", "widgetLabel": "Ask about plans"}'{
"productName": "Example App",
"agentName": "Robin",
"greeting": "Hi, I can answer questions about plans and features. What are you looking for?",
"voice": "cedar",
"widgetLabel": "Ask about plans",
"allowedOrigins": [
"https://www.example.com"
],
"enabled": false,
"agentConfigured": true
}How do you switch customer calls on?
Send {"enabled": true} once the agent is ready, and calls can start from any of its allowed origins. Send {"enabled": false} to stop new customer calls.
The dashboard keeps its switch off until the setup steps are done: approved knowledge for that agent, saved agent settings, an allowed origin and a finished test call. The API doesn’t check these steps, and test calls can only be made in the dashboard, so complete them there before you send enabled: true.
Switching calls or handover on or off and changing allowed origins email the workspace owner, naming the token that made the change. Changes to greetings, instructions and other text send no email, so keep your settings in version control if several people or tools change them.
Can the API turn on human handover?
Yes, once the agent has a verified team number. Human handover is an early release. Your team verifies a UK or US phone number in the dashboard’s Settings, separately for support and sales, and then {"escalationEnabled": true} turns handover on for that agent. A caller can then choose Talk to a human, and the person who answers hears a private briefing before the caller is connected. Customer routing is still being tested, so keep your usual contact options.
Turning handover on before that agent’s number is verified returns 403 with “Verify your team phone number in Settings before enabling handover.” Sending {"escalationEnabled": false} turns it off, and removing the verified number in Settings turns it off too.
Which errors can an update return?
Validation errors return 400 with a message that names the problem:
- “Invalid greeting.”, or the same with another field’s name: a value of the wrong type, or longer than its limit.
- “Your product needs a name.” or “Your agent needs a name.”: an empty name.
- “Choose Marin or Cedar.”: any other voice.
- “Choose a valid hex color.”: a colour that isn’t # followed by six hex digits.
- “Add up to 10 allowed origins.” or “Use an HTTPS origin without a path, such as https://yourproduct.com.”: see the allowed origins reference.
- “Provide an agent settings object.”: a body that isn’t a JSON object.
- Other statuses: 403 for sending humanNumber, or for turning on escalationEnabled before that agent’s team number is verified, 409 for a collision, which you can resend, and 401 for a token problem.