Bot Intent Mapping Failure: Zendesk Article IDs Returning 404 in Genesys Cloud Knowledge Search

Architect & Flows
1

Does anyone know how to properly map Zendesk article IDs to Genesys Cloud Knowledge Search articles during a bot migration? We are hitting a wall with the AI Bot configuration.

  • Environment: Genesys Cloud (EU1)
  • Source: Zendesk Support (v2 API)
  • Bot Type: AI Bot (v1)
  • Integration: Knowledge Search (Standard)
  • Error: 404 Not Found on POST /api/v2/bots/{botId}/intent-mappings

We are migrating a large knowledge base from Zendesk to Genesys Cloud. In Zendesk, we relied heavily on the numeric article_id for routing and analytics. The goal is to maintain these IDs in the Genesys Cloud article metadata to keep our historical reporting intact.

The process:

  1. Import articles into Genesys Cloud Knowledge Search using the bulk import API. The external_id field is populated with the original Zendesk article_id.
  2. Create intents in the AI Bot.
  3. Attempt to map these intents to the imported articles.

The problem occurs at step 3. When we try to associate an intent with an article using the Zendesk ID in the article_id parameter, the API returns a 404. It seems Genesys Cloud expects the internal article_id generated during import, not the custom external_id.

In Zendesk, the ID was the primary key. In Genesys Cloud, the external_id is just a metadata field. We cannot manually update thousands of mappings. Is there a bulk API to retrieve the internal article_id based on the external_id? Or is there a way to force the AI Bot to recognize the external_id as the primary lookup key for intent mappings? This feels like a major gap in the migration tooling compared to the flexibility we had with Zendesk’s API.

2

This looks like a payload structure mismatch rather than an authentication failure. When migrating from Zendesk, the external article IDs often need to be mapped to the internal Genesys Cloud Knowledge Base object IDs before the intent mapping endpoint can resolve them. The 404 error suggests the system cannot locate the target article using the provided identifier in the current context.

Verify that the knowledgeArticleId field in your request body corresponds to a valid, published article within the specific Knowledge Base ID configured in your bot’s settings. Ensure the article status is PUBLISHED and not DRAFT or ARCHIVED.

Here is the corrected payload structure for the intent mapping update:

{
 "intentName": "reset_password",
 "knowledgeArticleId": "kb-article-uuid-here",
 "knowledgeBaseId": "kb-base-uuid-here",
 "confidenceThreshold": 0.85
}

Check the Knowledge Search logs for indexing delays. If the article was recently imported, it may not yet be searchable. Re-run the mapping after the index completes.