---
title: "CreateConversation"
method: POST
path: "/v3/conversations"
tags: ["Conversations"]
---

# CreateConversation

`POST /v3/conversations`

Create a new Conversation.

POST to this method with a
* Bot being the bot creating the conversation
* IsGroup set to true if this is not a direct message (default is false)
* Members array contining the members you want to have be in the conversation.

The return value is a ResourceResponse which contains a conversation id which is suitable for use
in the message payload and REST API uris.

Most channels only support the semantics of bots initiating a direct message conversation.  An example of how to do that would be:

```
var resource = await connector.conversations.CreateConversation(new ConversationParameters(){ Bot = bot, members = new ChannelAccount[] { new ChannelAccount("user1") } );
await connect.Conversations.SendToConversationAsync(resource.Id, new Activity() ... ) ;

```

## Request body

- ConversationParameters — Parameters for creating a new conversation
  - `isGroup` boolean — IsGroup
  - `bot` ChannelAccount — Channel account information needed to route a message
    - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
    - `name` string — Display friendly name
    - `role` 'user' | 'bot'
  - `members` ChannelAccount[] — Members to add to the conversation
    - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
    - `name` string — Display friendly name
    - `role` 'user' | 'bot'
  - `topicName` string — (Optional) Topic of the conversation (if supported by the channel)
  - `activity` Activity — An Activity is the basic communication type for the Bot Framework 3.0 protocol
    - `type` 'message' | 'contactRelationUpdate' | 'conversationUpdate' | 'typing' | 'ping' | 'endOfConversation' | 'event' | 'invoke' | 'deleteUserData' | 'messageUpdate' | 'messageDelete' | 'installationUpdate' | 'messageReaction' | 'suggestion' | 'trace' — Types of Activities
    - `id` string — ID of this activity
    - `timestamp` string, date-time — UTC Time when message was sent (set by service)
    - `localTimestamp` string, date-time — Local time when message was sent (set by client, Ex: 2016-09-23T13:07:49.4714686-07:00)
    - `serviceUrl` string — Service endpoint where operations concerning the activity may be performed
    - `channelId` string — ID of the channel where the activity was sent
    - `from` ChannelAccount — Channel account information needed to route a message
      - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
      - `name` string — Display friendly name
      - `role` 'user' | 'bot'
    - `conversation` ConversationAccount — Channel account information for a conversation
      - `isGroup` boolean — Indicates whether the conversation contains more than two participants at the time the activity was generated
      - `conversationType` string — Indicates the type of the conversation in channels that distinguish between conversation types
      - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
      - `name` string — Display friendly name
      - `role` 'user' | 'bot'
    - `recipient` ChannelAccount — Channel account information needed to route a message
      - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
      - `name` string — Display friendly name
      - `role` 'user' | 'bot'
    - `textFormat` 'markdown' | 'plain' | 'xml' — Text format types
    - `attachmentLayout` 'list' | 'carousel' — Attachment layout types
    - `membersAdded` ChannelAccount[] — Members added to the conversation
      - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
      - `name` string — Display friendly name
      - `role` 'user' | 'bot'
    - `membersRemoved` ChannelAccount[] — Members removed from the conversation
      - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
      - `name` string — Display friendly name
      - `role` 'user' | 'bot'
    - `reactionsAdded` MessageReaction[] — Reactions added to the activity
      - `type` 'like' | 'plusOne' — Message reaction types
    - `reactionsRemoved` MessageReaction[] — Reactions removed from the activity
      - `type` 'like' | 'plusOne' — Message reaction types
    - `topicName` string — The conversation's updated topic name
    - `historyDisclosed` boolean — True if prior history of the channel is disclosed
    - `locale` string — The language code of the Text field
    - `text` string — Content for the message
    - `speak` string — SSML Speak for TTS audio response
    - `inputHint` 'acceptingInput' | 'ignoringInput' | 'expectingInput' — Indicates whether the bot is accepting, expecting, or ignoring input
    - `summary` string — Text to display if the channel cannot render cards
    - `suggestedActions` SuggestedActions — SuggestedActions that can be performed
      - `to` string[] — Ids of the recipients that the actions should be shown to. These Ids are relative to the channelId and a subset of all recipients of the activity
      - `actions` CardAction[] — Actions that can be shown to the user
        - `type` 'openUrl' | 'imBack' | 'postBack' | 'playAudio' | 'playVideo' | 'showImage' | 'downloadFile' | 'signin' | 'call' | 'payment' | 'messageBack' — Types of actions
        - `title` string — Text description which appears on the button
        - `image` string — Image URL which will appear on the button, next to text label
        - `text` string — Text for this action
        - `displayText` string — (Optional) text to display in the chat feed if the button is clicked
        - `value` object — Supplementary parameter for action. Content of this property depends on the ActionType
    - `attachments` Attachment[] — Attachments
      - `contentType` string — mimetype/Contenttype for the file
      - `contentUrl` string — Content Url
      - `content` object — Embedded content
      - `name` string — (OPTIONAL) The name of the attachment
      - `thumbnailUrl` string — (OPTIONAL) Thumbnail associated with attachment
    - `entities` Entity[] — Collection of Entity objects, each of which contains metadata about this activity. Each Entity object is typed.
      - `type` string — Entity Type (typically from schema.org types)
    - `channelData` object — Channel-specific payload
    - `action` string — ContactAdded/Removed action
    - `replyToId` string — The original ID this message is a response to
    - `label` string — Descriptive label
    - `valueType` string — Unique string which identifies the shape of the value object
    - `value` object — Open-ended value
    - `name` string — Name of the operation to invoke or the name of the event
    - `relatesTo` ConversationReference — An object relating to a particular point in a conversation
      - `activityId` string — (Optional) ID of the activity to refer to
      - `user` ChannelAccount — Channel account information needed to route a message
        - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
        - `name` string — Display friendly name
        - `role` 'user' | 'bot'
      - `bot` ChannelAccount — Channel account information needed to route a message
        - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
        - `name` string — Display friendly name
        - `role` 'user' | 'bot'
      - `conversation` ConversationAccount — Channel account information for a conversation
        - `isGroup` boolean — Indicates whether the conversation contains more than two participants at the time the activity was generated
        - `conversationType` string — Indicates the type of the conversation in channels that distinguish between conversation types
        - `id` string — Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)
        - `name` string — Display friendly name
        - `role` 'user' | 'bot'
      - `channelId` string — Channel ID
      - `serviceUrl` string — Service endpoint where operations concerning the referenced conversation may be performed
    - `code` 'unknown' | 'completedSuccessfully' | 'userCancelled' | 'botTimedOut' | 'botIssuedInvalidMessage' | 'channelFailed' — Codes indicating why a conversation has ended
    - `expiration` string, date-time — DateTime to expire the activity as ISO 8601 encoded datetime
    - `importance` string — Importance of this activity {Low|Normal|High}, null value indicates Normal importance see ActivityImportance)
    - `deliveryMode` string — Hint to describe how this activity should be delivered. Currently: null or "Default" = default delivery "Notification" = notification semantics
    - `textHighlights` TextHighlight[] — TextHighlight in the activity represented in the ReplyToId property
      - `text` string — plain text fragment to highlight
      - `occurence` integer — index of occurence of the Text (Starting at 1)
  - `channelData` object — Channel specific payload for creating the conversation

## Response `200`

An object will be returned containing 
* the ID for the conversation
* ActivityId for the activity if provided.  If ActivityId is null then the channel doesn't support returning resource id's for activity.

- ConversationResourceResponse — A response containing a resource
  - `activityId` string — ID of the Activity (if sent)
  - `serviceUrl` string — Service endpoint where operations concerning the conversation may be performed
  - `id` string — Id of the resource

## Other responses

- `201` — An object will be returned containing * the ID for the conversation * ActivityId for the activity if provided. If ActivityId is null then the channel doesn't support returning resource id's for activity.
- `202` — An object will be returned containing * the ID for the conversation * ActivityId for the activity if provided. If ActivityId is null then the channel doesn't support returning resource id's for activity.
- `default` — The operation failed and the response is an error object describing the status code and failure.

---

[API](https://skmtc.net/poshbotio/apis/microsoft-bot-connector-api-v3-0.md) · [All operations](https://skmtc.net/poshbotio/apis/microsoft-bot-connector-api-v3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poshbotio/microsoft-bot-connector-api-v3-0/versions/ea45ea47a3fb/schema)