---
updatedAt: 2026-08-14T14:42:17.000Z
agentTools:
  projectIndex: https://customerly.readme.io/llms.txt
---

# Update conversation attributes

Updates or adds custom attributes to an existing conversation. Attributes are merged with existing ones.

### Behavior
- Attributes are merged incrementally (only specified attributes are updated)
- Existing attributes not included in the request remain unchanged
- An attribute that is not defined yet on the project is created automatically, guessing its type from the
  submitted value (text, number, date or boolean)
- Sending `null` as value empties the attribute without removing it

### Response Data
The endpoint returns the conversation id together with **all** the attributes of the conversation, both the
updated and the unchanged ones.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Customerly API",
    "description": "<p>The Customerly API allows you to integrate your platform with <a href=\"https://www.customerly.io\">Customerly</a>'s suite of customer support, marketing automation, and customer satisfaction tools. This document provides an overview of how to authenticate and interact with the API.</p>\n\n<h2>Authentication</h2>\n<p>To interact with the Customerly REST API, you must authenticate your requests using an access token.</p>\n\n<h3>Get Access Token</h3>\n<ol>\n    <li>Log in to Customerly.</li>\n    <li>Follow the tutorial: <a href=\"https://docs.customerly.io/en/api/how-to-obtain-your-api-access-token-in-customerly\">How to Obtain Your API Access Token in Customerly</a>.</li>\n</ol>\n\n<h3>Using Access Token</h3>\n<p>Include the access token as a Bearer token in the <code>Authorization</code> header of your HTTP requests:</p>\n<pre>Authorization: Bearer YOUR_ACCESS_TOKEN</pre>\n\n<hr>\n\n<h2>Error Handling</h2>\n<p>When an error occurs, the API returns a JSON response with the following structure:</p>\n\n<pre>{\n  \"error\": {\n    \"code\": \"error_code_here\",\n    \"message\": \"A human-readable error description.\",\n    \"http_status\": 400,\n    \"details\": { ... }\n  }\n}</pre>\n\n<p>The <code>details</code> field is optional and provides additional context when available (e.g., validation errors).</p>\n\n<h3>Example Error Response</h3>\n<pre>{\n  \"error\": {\n    \"code\": \"auth_missing_authorization_header\",\n    \"message\": \"The Authorization header is missing.\",\n    \"http_status\": 401\n  }\n}</pre>\n\n<h3>Error Codes Reference</h3>\n<p>Below is the complete list of error codes that may be returned by the API:</p>\n\n<table>\n    <thead>\n        <tr>\n            <th>Code</th>\n            <th>Description</th>\n        </tr>\n    </thead>\n    <tbody>\n        <tr><td><code>account_email_not_verified</code></td><td>The account email is not verified.</td></tr><tr><td><code>account_not_found</code></td><td>Account not found.</td></tr><tr><td><code>app_banned</code></td><td>The application is banned.</td></tr><tr><td><code>app_insolvent</code></td><td>The application is insolvent.</td></tr><tr><td><code>app_not_active</code></td><td>The application is not active.</td></tr><tr><td><code>attachment_file_too_large</code></td><td>Attachment file size exceeds the maximum allowed (5MB).</td></tr><tr><td><code>attachment_too_many_files</code></td><td>Too many attachments.</td></tr><tr><td><code>attribute_invalid_format</code></td><td>One or more attributes have invalid format. Attribute names must be alphanumeric (underscores and hyphens allowed), and values must be simple types (strings, numbers, booleans), not arrays or objects.</td></tr><tr><td><code>auth_invalid_access_token</code></td><td>The access token is invalid.</td></tr><tr><td><code>auth_missing_authorization_header</code></td><td>The Authorization header is missing.</td></tr><tr><td><code>company_conflicting_identifiers</code></td><td>The provided identifiers point to different companies. Please provide only one identifier or ensure they all refer to the same company.</td></tr><tr><td><code>company_custom_company_id_required</code></td><td>To create a new company, custom_company_id is required.</td></tr><tr><td><code>company_identifier_required</code></td><td>At least one identifier (company_id or custom_company_id) is required.</td></tr><tr><td><code>company_invalid_filters</code></td><td>The filters are invalid. Check the predicate structure, audience, and condition targets/operations.</td></tr><tr><td><code>company_not_found</code></td><td>Company not found.</td></tr><tr><td><code>contact_cannot_merge_into_itself</code></td><td>A contact cannot be merged into itself. The surviving and victim contacts must be different.</td></tr><tr><td><code>contact_conflicting_identifiers</code></td><td>The provided identifiers point to different contacts. Please provide only one identifier or ensure they all refer to the same contact.</td></tr><tr><td><code>contact_identifier_required</code></td><td>At least one identifier (user_id, email, custom_contact_id, or whatsapp_number) is required.</td></tr><tr><td><code>contact_invalid_filters</code></td><td>The filters are invalid. Check the predicate structure, audience, and condition targets/operations.</td></tr><tr><td><code>contact_is_spam</code></td><td>Cannot send messages from contacts marked as spam.</td></tr><tr><td><code>contact_merge_conflict</code></td><td>One of the contacts is already involved in an ongoing merge, or has already been merged into another contact. Wait for any pending merge to complete before retrying.</td></tr><tr><td><code>contact_not_found</code></td><td>Contact not found.</td></tr><tr><td><code>conversation_access_denied</code></td><td>Access to this conversation is denied.</td></tr><tr><td><code>conversation_assigned_to_ai</code></td><td>Cannot reply to a conversation assigned to AI. The conversation must be assigned to a human account first.</td></tr><tr><td><code>conversation_channel_not_supported</code></td><td>Cannot reply to this conversation channel. Only email and in_app channels support replies via API. WhatsApp conversations accept approved templates through POST /v2/conversations/{conversation_id}/whatsapp/templates/send.</td></tr><tr><td><code>conversation_email_channel_not_supported</code></td><td>The email channel is not supported for conversation messages. You should verify domain to send email.</td></tr><tr><td><code>conversation_frozen</code></td><td>This conversation has been frozen and cannot accept new messages.</td></tr><tr><td><code>conversation_missing_content_or_attachments</code></td><td>Either content or attachments must be provided for the conversation message.</td></tr><tr><td><code>conversation_not_found</code></td><td>The conversation was not found.</td></tr><tr><td><code>conversation_not_open_for_snooze</code></td><td>Only open conversations can be snoozed.</td></tr><tr><td><code>message_range_invalid_order</code></td><td>`to` must be greater than or equal to `from`.</td></tr><tr><td><code>message_range_exceeded</code></td><td>The range between `from` and `to` exceeds the maximum allowed window.</td></tr><tr><td><code>document_not_found</code></td><td>The document was not found.</td></tr><tr><td><code>document_currently_processing</code></td><td>The document is currently being processed and cannot be modified.</td></tr><tr><td><code>document_file_required</code></td><td>A file is required for upload.</td></tr><tr><td><code>document_file_invalid</code></td><td>The uploaded file is invalid.</td></tr><tr><td><code>document_file_too_large</code></td><td>The file size exceeds the maximum allowed (100MB).</td></tr><tr><td><code>document_file_type_not_allowed</code></td><td>Invalid file type. Only PDF, Word and TXT documents are allowed.</td></tr><tr><td><code>document_conflicting_identifiers</code></td><td>Cannot specify both document_id and custom_document_id at the same time.</td></tr><tr><td><code>document_folder_not_found</code></td><td>The document folder was not found.</td></tr><tr><td><code>document_folder_parent_not_found</code></td><td>The parent folder was not found.</td></tr><tr><td><code>document_folder_destination_not_found</code></td><td>The destination folder was not found.</td></tr><tr><td><code>document_folder_already_exists</code></td><td>A document folder with this name or custom folder ID already exists.</td></tr><tr><td><code>document_folder_invalid_parent</code></td><td>The parent folder is invalid. Only root folders (without a parent) can be used as a parent.</td></tr><tr><td><code>document_folder_conflicting_identifiers</code></td><td>Cannot specify both folder_id and custom_folder_id at the same time.</td></tr><tr><td><code>document_folder_conflicting_folder_identifiers</code></td><td>Cannot specify both folder_id and polymorphic_folder_id at the same time.</td></tr><tr><td><code>event_invalid_format</code></td><td>The event name is invalid. Event names must be alphanumeric (letters, numbers, and underscores only), cannot be empty, and cannot use the reserved prefix \"customerly_\".</td></tr><tr><td><code>knowledge_base_collection_not_found</code></td><td>The knowledge base collection was not found.</td></tr><tr><td><code>knowledge_base_invalid_locale</code></td><td>The provided locale is invalid.</td></tr><tr><td><code>knowledge_base_locale_not_in_settings</code></td><td>The locale is not configured in knowledge base settings.</td></tr><tr><td><code>knowledge_base_slug_conflict</code></td><td>A collection or article with this slug already exists in this locale/collection.</td></tr><tr><td><code>knowledge_base_multi_locale_forbidden</code></td><td>Multi-locale feature is not available on your plan.</td></tr><tr><td><code>knowledge_base_parent_locale_mismatch</code></td><td>Parent collection must be in the same locale as the child collection.</td></tr><tr><td><code>knowledge_base_parent_too_deep</code></td><td>Collections can only be nested up to 2 levels deep. The parent collection already has a parent.</td></tr><tr><td><code>knowledge_base_parent_missing_linked_locales</code></td><td>The new parent collection does not have linked collections for all the locales of the child linked collections.</td></tr><tr><td><code>knowledge_base_article_not_found</code></td><td>The knowledge base article was not found.</td></tr><tr><td><code>knowledge_base_invalid_status</code></td><td>Status must be 0 (draft) or 1 (published).</td></tr><tr><td><code>knowledge_base_invalid_writer</code></td><td>The writer account ID is invalid.</td></tr><tr><td><code>knowledge_base_writer_not_in_app</code></td><td>The writer must be a valid account in your app.</td></tr><tr><td><code>permission_denied</code></td><td>You don't have permission to perform this action.</td></tr><tr><td><code>request_conflict</code></td><td>Conflict.</td></tr><tr><td><code>request_forbidden</code></td><td>Forbidden.</td></tr><tr><td><code>request_length_required</code></td><td>Length required.</td></tr><tr><td><code>request_locked</code></td><td>Locked.</td></tr><tr><td><code>request_method_not_allowed</code></td><td>Method not allowed.</td></tr><tr><td><code>request_not_acceptable</code></td><td>Not acceptable.</td></tr><tr><td><code>request_not_found</code></td><td>Not found.</td></tr><tr><td><code>request_not_valid</code></td><td>The request is not valid.</td></tr><tr><td><code>request_invalid_json</code></td><td>The request body contains invalid JSON.</td></tr><tr><td><code>request_body_must_be_object</code></td><td>The request body must be a JSON object.</td></tr><tr><td><code>request_payment_required</code></td><td>Payment required.</td></tr><tr><td><code>request_too_many_requests</code></td><td>Too many requests.</td></tr><tr><td><code>request_unauthorized</code></td><td>Unauthorized.</td></tr><tr><td><code>request_unprocessable</code></td><td>Unprocessable entity.</td></tr><tr><td><code>segment_not_found</code></td><td>Segment not found.</td></tr><tr><td><code>segment_invalid_filters</code></td><td>The filters are invalid. Check the predicate structure, audience, and condition targets/operations.</td></tr><tr><td><code>segment_circular_dependency</code></td><td>The segment cannot be saved: a circular dependency was detected between segments.</td></tr><tr><td><code>segment_deletion_in_progress</code></td><td>The segment is already being deleted.</td></tr><tr><td><code>segment_used_as_filter</code></td><td>The segment cannot be deleted because it is used as a filter in other segments, workflows, surveys, or automations. Remove the dependencies first.</td></tr><tr><td><code>server_internal_error</code></td><td>An internal server error occurred, please try again later.</td></tr><tr><td><code>team_not_found</code></td><td>Team not found.</td></tr><tr><td><code>validation_field_required</code></td><td>This field is required.</td></tr><tr><td><code>validation_invalid_email</code></td><td>The email address is invalid.</td></tr><tr><td><code>validation_invalid_length</code></td><td>The field length is invalid.</td></tr><tr><td><code>validation_invalid_type</code></td><td>The field type is invalid.</td></tr><tr><td><code>validation_invalid_value</code></td><td>The field value is invalid.</td></tr><tr><td><code>validation_invalid_whatsapp_number</code></td><td>The WhatsApp number is invalid. It must be in the format +123456789.</td></tr><tr><td><code>validation_invalid_user_include_parameter</code></td><td>The user include parameter is invalid. Valid options are: events, companies, segments, notes.</td></tr><tr><td><code>whatsapp_contact_without_number</code></td><td>The contact does not have a WhatsApp number.</td></tr><tr><td><code>whatsapp_conversation_not_whatsapp</code></td><td>The conversation is not a WhatsApp conversation.</td></tr><tr><td><code>whatsapp_number_ambiguous</code></td><td>The app has more than one WhatsApp business number. Specify which one to send from with whatsapp_business_number.</td></tr><tr><td><code>whatsapp_number_not_found</code></td><td>No connected WhatsApp business number was found.</td></tr><tr><td><code>whatsapp_number_stopped</code></td><td>The WhatsApp business number is stopped and cannot send messages.</td></tr><tr><td><code>whatsapp_template_missing_parameters</code></td><td>One or more required template parameters are missing.</td></tr><tr><td><code>whatsapp_template_not_found</code></td><td>The WhatsApp template was not found, or it is not approved.</td></tr><tr><td><code>whatsapp_template_not_text_only</code></td><td>Only text-only WhatsApp templates are supported. Templates with buttons or media headers cannot be sent through the API.</td></tr><tr><td><code>whatsapp_template_waba_mismatch</code></td><td>The template does not belong to the WhatsApp Business Account of the selected number.</td></tr>\n    </tbody>\n</table>",
    "contact": {
      "email": "developers@customerly.io"
    },
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://api.customerly.io",
      "description": "Production server"
    }
  ],
  "paths": {
    "/v2/conversations/{conversation_id}/attributes": {
      "patch": {
        "tags": [
          "Conversations"
        ],
        "summary": "Update conversation attributes",
        "description": "Updates or adds custom attributes to an existing conversation. Attributes are merged with existing ones.\n\n### Behavior\n- Attributes are merged incrementally (only specified attributes are updated)\n- Existing attributes not included in the request remain unchanged\n- An attribute that is not defined yet on the project is created automatically, guessing its type from the\n  submitted value (text, number, date or boolean)\n- Sending `null` as value empties the attribute without removing it\n\n### Response Data\nThe endpoint returns the conversation id together with **all** the attributes of the conversation, both the\nupdated and the unchanged ones.",
        "operationId": "patch_officialcustomerly_apipublic_v2_conversations_conversationsattributes_updateconversationattributes",
        "parameters": [
          {
            "name": "conversation_id",
            "in": "path",
            "description": "The conversation id",
            "required": true,
            "schema": {
              "type": "integer",
              "pattern": "\\d+"
            },
            "example": 12
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "attributes"
                ],
                "properties": {
                  "attributes": {
                    "type": "object",
                    "example": {
                      "order_id": "A-1029",
                      "refund_requested": true,
                      "items_count": 3
                    }
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation attributes updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationAttributesModel"
                }
              }
            }
          },
          "401": {
            "description": "Authentication credentials are missing or invalid"
          },
          "403": {
            "description": "You don't have permission to update this conversation"
          },
          "404": {
            "description": "Conversation not found"
          },
          "422": {
            "description": "Validation error. Possible causes: attributes must be an object, attribute names contain invalid characters (only alphanumeric, underscores, and hyphens allowed), or attribute values are arrays/objects (only simple types allowed: strings, numbers, booleans)."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ConversationAttributesModel": {
        "required": [
          "conversation_id",
          "attributes"
        ],
        "properties": {
          "conversation_id": {
            "description": "Unique identifier for the conversation",
            "type": "integer",
            "example": 1
          },
          "attributes": {
            "description": "All the attributes of the conversation, including the ones left unchanged",
            "type": "object",
            "example": {
              "order_id": "A-1029",
              "refund_requested": "1"
            }
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ],
  "tags": [
    {
      "name": "Conversations"
    }
  ]
}
```