Genesys Cloud - Developer Community!

Hello,

I'm trying to understand the behavior of the endpoint:

POST /api/v2/conversations/calls/{conversationId}/participants/user/{userId}

The official documentation description says: "Add participants on behalf of a user", which makes it sound like it can add a new participant using userId only, to a conversation.

However, in practice:

• If the userId in the path is not already a participant in the conversation, the API returns:

  
  
  
  
  
  
  Error calling PostConversationsCallParticipantsUserUserId: {"message":"User 18ee7 is not a participant in the conversation.","code":"not.found","status":404,"contextId":"7b5d4a23-1c6d-4ef3-90d5-28c9306c133d","details":[],"errors":[]}
  
  
  
  

• It seems that this endpoint can only update or act on an existing participant, not create a new one.

I want to clarify:

1. Is /participants/user/{userId} intended only to update existing participants, despite the wording "add participants" in the API Docs?

2. If so, why does the description use "add participants"?

3. What is the correct endpoint for adding a new participant using auserId to an ongoing conversation, without user context, with client credentials?

Any clarification or official guidance would be very helpful - the documentation is a bit misleading.

Thank you!

#PlatformAPI

------------------------------
Marisa Grasso
------------------------------

Olá! Excelente análise, e sim - o comportamento desse endpoint pode gerar confusão pela forma como está descrito na documentação.

---

O que este endpoint realmente faz

POST /api/v2/conversations/calls/{conversationId}/participants/user/{userId}

Apesar da descrição mencionar "Add participants on behalf of a user", este endpoint não adiciona um novo participante à chamada.
Ele é usado apenas para atuar sobre um participante que já está na conversa, por exemplo:

• Mutar / desmutar

• Colocar em espera

• Atualizar estado

• Encerrar participação

Se o userId informado não estiver presente na conversa, a API retorna:

404 - User is not a participant in the conversation

Ou seja:
 Este endpoint só funciona para participantes já existentes.

 Endpoint correto para adicionar um novo participante

Para adicionar um novo participante (interno ou externo), use:

POST /api/v2/conversations/calls/{conversationId}/participants

Exemplo – adicionando um usuário interno à chamada:

{
  "userId": "abcde-12345-67890",
  "conference": true
}

Exemplo – adicionando um número externo:

{
  "address": "tel:+15551234567",
  "conference": true
}

Observação: conference: true garante que os participantes atuais permaneçam na chamada ao incluir o novo participante.

---

Resumindo

---

📝 Sobre o texto da documentação

Você está certo em observar que a frase "add participants" nesta rota é ambígua.
O "add" se refere ao conjunto de operações de participantes, mas esta rota especificamente não cria participantes. Vale abrir um doc feedback caso queira reportar o ponto - é algo que aparece para outros devs também.

------------------------------
Fernando Sotto dos Santos
Consultor Grupo Casas Bahia
------------------------------