I am trying to configure a new Web Messaging deployment via the API. The goal is to set a specific brand color and move the launcher to the left side of the screen. I am using the PUT /api/v2/conversations/webmessaging/deployments/{webMessagingDeploymentId} endpoint.
The documentation says the configuration should be passed in the body. Here is the JSON payload I am sending:
{
"configuration": {
"launcher": {
"position": "left",
"color": "#FF5733"
}
}
}
The API returns a 200 OK. No errors. The response body looks correct and reflects the changes. I verified the deployment ID is correct. I can see the deployment in the UI under Web Messaging. The ID matches.
But when I load the chat widget on the test page, the launcher is still on the right. The color is the default blue. It is not picking up the #FF5733 hex code.
I tried clearing the browser cache. I tried incognito mode. Same result. I also tried setting the color as a named string like “red” instead of hex. Still default blue.
Is there a specific path in the JSON object for the theme? Or does the launcher position require a separate field? I have checked the OpenAPI spec for WebMessagingDeployment. The configuration object seems to just have a string field for settings in some versions, but the UI suggests structured JSON works.
Here is the full request headers I am using:
Content-Type: application/json
Authorization: Bearer <valid_token>
Any idea why the visual changes are not persisting to the frontend?
The docs for the Web Messaging deployment API are a bit sparse on the exact structure for the configuration object, especially when it comes to the launcher styling. I hit this wall recently when trying to rebrand a client’s widget. The issue usually isn’t the endpoint itself, but how the launcher object is nested and what properties are actually accepted. You can’t just slap a hex code in there; you need to target the specific style properties.
Here is the working payload structure that actually sticks. Notice the style object inside launcher. That’s where the color lives.
{
"configuration": {
"launcher": {
"position": "LEFT",
"style": {
"primaryColor": "#007bff",
"backgroundColor": "#ffffff",
"iconColor": "#ffffff"
},
"enabled": true
},
"widget": {
"title": "Support Chat",
"enabled": true
}
}
}
Make sure you’re using the PUT method, not PATCH, unless you’re only updating a single field. If you use PATCH with the full object, you might accidentally wipe out default settings that aren’t explicitly in your payload. The position property accepts LEFT or RIGHT as strings. No need for CSS values like left: 0.
Also, double-check your OAuth scopes. You need webmessaging:deployment and webmessaging:deployment:write. If you’re getting a 403, it’s almost certainly a scope issue. I wasted two hours on this last week because my service account had webmessaging:deployment:view but not the write permission. The API returns a generic 400 sometimes if the JSON structure is slightly off, so validate your payload against the schema first.
One thing to watch out for is the caching. After you push the update via API, the change might not reflect immediately in the browser. Clear your cache or try an incognito window to verify the position and color actually updated. If it still shows the old config, wait a minute and try again. The propagation isn’t instant.