Looking for advice on programmatically setting wrap-up codes after an interaction ends using the Conversations API.
The POST request to /api/v2/conversations/interactions/{id} with payload {"wrapUpCode": {"id": "12345-abc"}} consistently returns 422 Unprocessable Entity. The documentation implies the interaction must be in closed state, yet the status field confirms closed. I am migrating logic from Twilio Functions where this is handled via a simple status update attribute, but the GC endpoint rejects the payload regardless of whether I use wrapUpCode or wrapupCode. The response body contains {"message": "Invalid wrap-up code for interaction type"}. Is there a specific pre-condition on the interaction object or a different endpoint required for this operation?
Ah, this is a recognized issue…
The POST request to /api/v2/conversations/interactions/{id} with payload {“wrapUpCode”: {“id”: “12345-abc”}} consistently returns 422 Unprocessable Entity.
The endpoint requires the full wrap-up code object, not just the ID. Use the GET endpoint to fetch the code first.
# Fetch code details first
code = platform_client.wrapupcodes_api.get_wrapupcode(code_id)
# Then pass the full object
interaction.wrap_up_code = code
Have you tried switching to the PATCH method on the interaction endpoint instead of using POST? The documentation often conflates these methods when discussing updating terminated interactions, but POST is typically reserved for creating new resources or initiating specific actions like transferring. Since the interaction is already in a closed state, you are essentially updating an existing record. In my recent migration from Five9, I found that CXone’s API is strict about HTTP verbs for state changes. A POST to a closed interaction usually triggers validation errors because the system expects a creation payload, whereas a PATCH allows you to merge specific fields like the wrap-up code into the existing JSON body without requiring the full object.
Here is the Python snippet using the PureCloudPlatformClientV2 SDK that resolved the 422 error for me. Note that you must ensure the wrapUpCode object includes the id and potentially the name if your org requires it, though just the ID usually suffices if the code is public. I also had to ensure my OAuth token included the conversations:read and conversations:write scopes.
from purecloudplatformclientv2 import Configuration, ApiClient, ConversationsApi, WrapupCode
# Initialize API client
config = Configuration()
config.access_token = "your_access_token"
api_client = ApiClient(config)
conversations_api = ConversationsApi(api_client)
# Define the wrap-up code object
wrap_up = WrapupCode(id="12345-abc")
# Create the patch body
patch_body = {
"wrapUpCode": wrap_up
}
# Execute PATCH request
try:
response = conversations_api.patch_conversation_interaction(interaction_id="your_interaction_id", body=patch_body)
print(f"Wrap-up set successfully: {response}")
except Exception as e:
print(f"Error: {e}")
One gotcha I ran into was that the endpoint sometimes returns a 422 if the interaction is still in a “wrapping” state rather than fully “closed.” Check the state field in the interaction response. If it says “wrapping,” you might need to wait a few seconds or explicitly terminate the interaction first using the terminate endpoint. Also, ensure the wrap-up code ID belongs to the same user context or is a global code, otherwise, you might hit permission issues even with the correct HTTP verb. This approach bypassed the payload structure issues mentioned in previous replies.
It depends, but generally… 422 Unprocessable Entity when hitting /api/v2/conversations/interactions/{id} usually means the payload structure violates the strict schema for terminated interactions. The suggestion above to use PATCH is directionally correct, but the real issue is likely the missing participant context. You cannot attach a wrap-up code to an interaction ID alone; you must specify which participant (agent, customer, or queue) is receiving the code. The API rejects the request because it doesn’t know who is wrapping up. Here is the correct JSON payload structure for a POST to /api/v2/conversations/interactions/{id}/participants:
{
"participants": [
{
"id": "participant-id-from-interaction-get",
"wrapUpCode": {
"id": "12345-abc",
"name": "Sales Closed"
}
}
]
}
Ensure you are using the CONVERSATION:WRITE scope. If you are still getting 422, check the errorInfo field in the response body for specific validation failures. Often, the id in the wrapUpCode object must match an active wrap-up code in your organization’s configuration. You can verify this by running a GET against /api/v2/users/wrapupcodes/{userId} to confirm the code exists and is enabled. I have seen cases where the code exists but is not assigned to the user’s profile, causing the API to reject the association. Also, ensure the interaction is actually in TERMINATED state. If it is WRAPPINGUP, you cannot set the code again; you must wait for the state to transition or use the specific wrap-up endpoint for active participants. My Postman collection handles this by chaining the GET interaction details, filtering for the agent participant ID, and then POSTing the update with the full object structure. Do not rely on the interaction ID alone for participant-specific attributes.
If you check the docs, they mention the interaction must be fully terminated, but it rarely mentions the participant ID requirement explicitly. 422 Unprocessable Entity here means the server cannot map the wrap-up code to a specific leg. You are likely hitting this because you are sending the code at the interaction level without specifying which participant applies to it.
In my quality scoring scripts, I always fetch the participant details first to ensure the ID matches the agent or queue. The payload must include the participantId. Here is the correct structure:
{
"wrapUpCode": {
"id": "12345-abc",
"participantId": "agent-uuid-here"
}
}
Use PATCH on /api/v2/conversations/voice/{conversationId} instead of the interaction endpoint. The interaction endpoint is for metadata, not state changes. Ensure your OAuth scope includes conversation:write. If you still get 422, check the error body for invalidParticipantId. This usually resolves the issue immediately.