# Add participant to conversation

## Ensure the conversation has a specific participant

> Add a participant to the conversation if it hasn't already been added

```json
{"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[{"name":"conversation_participant","description":"Manage the participants of a conversation."}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateParticipant":{"nullable":true,"type":"object","oneOf":[{"type":"object","title":"User or flow participant","description":"Create a participant of the user or flow type.\n","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"ID of the flow or user."},"type":{"type":"string","description":"Participant type.","enum":["user","flow"]},"status":{"type":"string","description":"Participant status in the conversation. Defaults to `active`.","enum":["pending","invited","active"],"default":"active"}}},{"type":"object","title":"Participant with contact ID","description":"Create a participant based on an existing contact. It is optional to set the platformAddressSelector for a given contact to select the attribute for communication.\n","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"Contact ID."},"type":{"type":"string","description":"Participant type.","enum":["contact"]},"status":{"type":"string","description":"Participant status in the conversation. Defaults to `active`.","enum":["pending","invited","active"],"default":"active"},"contact":{"type":"object","description":"Contact identifier information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"nullable":true,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used.","nullable":true},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address.","nullable":true},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","nullable":true}}}}},{"type":"object","title":"Participant with contact identifier.","description":"Create a participant with an identifier value. The contact will be found, or otherwise created, based on the identifier value.\n","additionalProperties":false,"required":["contact","type"],"properties":{"contact":{"type":"object","description":"Contact identifier information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used.","nullable":true},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address."},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases.","nullable":true}},"required":["identifierValue"]},"type":{"type":"string","description":"Participant type.","enum":["contact"]},"status":{"type":"string","description":"Participant status in the conversation. Defaults to `active`.","enum":["pending","invited","active"],"default":"active"}}}]},"Participant":{"type":"object","description":"A participant who can send and receive messages in the conversation","title":"ConversationParticipant","additionalProperties":false,"properties":{"id":{"type":"string","description":"Participant ID, the meaning of this field depends on `type`. If `type` is `user` then it's a user ID, if `type` is `contact` then it's a contact ID, if `type` is `accessKey` then it's the access key ID, and so on.\n"},"displayName":{"type":"string","description":"The participant's name."},"avatarUrl":{"type":"string","description":"An URL to the participant's avatar."},"contact":{"$ref":"#/components/schemas/ParticipantContact"},"type":{"$ref":"#/components/schemas/ParticipantType"},"status":{"type":"string","description":"Participant status in the conversation. `pending` means it's pending approval, `invited` means it's pending acceptance from the participant, and `active` means the participant can send and receive messages.\n","enum":["pending","invited","active"],"default":"active"}},"required":["id","type"]},"ParticipantContact":{"type":"object","description":"The participant's contact information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddress":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."}}},"ParticipantType":{"type":"string","description":"Participant type. The main ones are `user`, `contact`, and `agent`. `user` is a user belonging to your Bird workspace, `contact` is one of your customers, `agent` is a customer service agent, and the remaining types represent system participants.\n","enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"]},"NotFoundError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ConflictError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ValidationError":{"title":"A validation error description","additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]}},"responses":{"notFound":{"description":"The resource specified in the URL was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"duplicate":{"description":"The resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictError"}}}},"validationFailed":{"description":"The request body did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/conversations/{conversationId}/participants":{"post":{"summary":"Ensure the conversation has a specific participant","operationId":"createConversationParticipant","description":"Add a participant to the conversation if it hasn't already been added","tags":["conversation_participant"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateParticipant"}}}},"responses":{"200":{"description":"Participant already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Participant"}}}},"201":{"description":"Participant was added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Participant"}}}},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/duplicate"},"422":{"$ref":"#/components/responses/validationFailed"}}}}}}
```

## Examples

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/c9c60caa-eaf5-4628-9687-91de4d452bfa/participants" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "type": "contact",
  "contact": {
    "identifierKey": "emailaddress",
    "identifierValue": "john.doe@bird.com"
  }
}'
```

{% endtab %}

{% tab title="Response (201 - Created)" %}

```json
{
  "id": "3954d22c-96f7-4bc3-817b-67b4d903ed90",
  "type": "contact",
  "status": "active",
  "displayName": "",
  "avatarUrl": "",
  "contact": {
    "identifierKey": "emailaddress",
    "identifierValue": "john.doe@bird.com",
    "platformAddress": "john.doe@bird.com"
  }
}
```

{% endtab %}
{% endtabs %}