Trying to understand the strict validation for participant addresses in POST /api/v2/conversations/calls. Background: I am building a Next.js server component to initiate outbound calls using the Platform SDK. Issue: The API returns a 400 Bad Request with error code invalid_request when I pass a valid tel: URI. Troubleshooting: I verified the to array structure matches the schema, but the error persists. Is there a specific format requirement for the type field when the initiator is an agent? Here is my payload: {"to": [{"type": "phone", "address": "tel:+1234567890"}]}.
const callPayload = {
to: [{ address: 'tel:+12025551234', addressType: 'telephone' }],
from: { address: 'tel:+12025559876', addressType: 'telephone' },
routingData: {
from: { id: 'system-user-id' },
to: { id: 'target-queue-id' }
}
};
await platformClient.ConversationsApi.postConversationsCalls(callPayload);
Check your addressType field. It is a common gotcha when moving from raw JSON to the SDK. The 400 error often stems from mismatched types between the string URI and the explicit addressType enum. Ensure you are not sending email or sms for a telephony target. Also, verify the from address belongs to an active application user with outbound permissions. I usually wrap these calls in a CDK Lambda layer to handle the OAuth token refresh automatically, preventing stale auth issues that masquerade as validation errors. If the payload structure is correct but the error persists, check the Genesys Cloud logs for routingContext mismatches. The API is strict about the routingData IDs existing in your organization.
Oh, this is a known issue…
Error: invalid_request - Malformed participant address
The SDK often strips the tel: scheme if addressType is explicitly set to telephone. Try passing just the raw number string in the address field. The API handles the URI construction internally when the type is specified. Check your Click CLI wrapper for this serialization quirk.
I think the addressType field is indeed the culprit here. When you set it to telephone, the Genesys Cloud API expects the raw E.164 number without the tel: URI scheme. The SDK serialization handles this strictly. I see this often in CRM integrations where developers copy-paste raw JSON examples. Here is the corrected payload structure for the PureCloudPlatformClientV2 SDK:
const payload = {
to: [{ address: '+12025551234', addressType: 'telephone' }],
from: { address: '+12025559876', addressType: 'telephone' },
routingData: {
from: { id: 'valid-user-id' },
to: { id: 'valid-queue-id' }
}
};
await platformClient.ConversationsApi.postConversationsCalls(payload);
Ensure your OAuth scopes include conversation:write. If you keep the tel: prefix, the validator rejects it as malformed because it assumes a URI format, which conflicts with the explicit type declaration. This is a common gotcha when switching between raw REST and SDK calls.
Check your address field serialization in the SDK object. The suggestion above hits the nail on the head regarding the tel: scheme. If you are using PureCloudPlatformClientV2 and setting addressType: 'telephone', the API parser strictly expects the raw E.164 string. It does not want the URI prefix.
const callPayload = {
to: [{
address: '+12025551234', // Raw E.164, NO 'tel:' prefix
addressType: 'telephone'
}],
from: {
address: '+12025559876', // Raw E.164
addressType: 'telephone'
},
routingData: {
from: { id: 'your-system-user-id' },
to: { id: 'your-queue-id' }
}
};
await platformClient.ConversationsApi.postConversationsCalls(callPayload);
This is a classic environment drift issue when moving configs. I see this constantly when promoting Terraform-managed Architect flows or integration configs from dev to staging. The raw JSON examples in the docs often show the full tel:+... URI because that is the standard REST payload format. However, the TypeScript SDK serializes objects differently. It validates the structure against the internal schema before sending. If you keep the tel: prefix while specifying telephone, the validator flags it as malformed because it sees a URI string where a phone number string is defined by the schema contract.
Remove the prefix. If you want to use the full URI, you must omit addressType entirely and let the API infer it, but that is less stable for automated routing. Stick to raw E.164 with explicit types for your outbound campaigns. It keeps the state consistent across your CI/CD pipeline and avoids those silent 400s that break your deployment gates.