# Create IM

{% hint style="info" %}
**Important**: This endpoint also allows the creation of Multi-party Instant Messages (MIM), which are not supported anymore. If you need to create a chat with several participants, please create a room instead.
{% endhint %}

## Create a new single or multi party instant message conversation between the caller and specified users.

> At least one user ID must be provided or\
> an error response will be sent.\
> \
> The caller is implicitly included in the members of the\
> created chat.\
> \
> Duplicate users will be included in the membership of the chat but\
> the duplication will be silently ignored.\
> \
> If there is an existing IM conversation with the same set of participants then\
> the id of that existing stream will be returned.\
> \
> This method was incorrectly specified to take a query parameter in\
> version 1.0 of this specification but now expects a JSON array of\
> user IDs in the body of the request.<br>

```json
{"openapi":"3.1.1","info":{"title":"Pod API","version":"20.17.1"},"servers":[{"url":"http://yourpodURL.symphony.com/pod"}],"paths":{"/v1/im/create":{"post":{"summary":"Create a new single or multi party instant message conversation between the caller and specified users.","description":"At least one user ID must be provided or\nan error response will be sent.\n\nThe caller is implicitly included in the members of the\ncreated chat.\n\nDuplicate users will be included in the membership of the chat but\nthe duplication will be silently ignored.\n\nIf there is an existing IM conversation with the same set of participants then\nthe id of that existing stream will be returned.\n\nThis method was incorrectly specified to take a query parameter in\nversion 1.0 of this specification but now expects a JSON array of\nuser IDs in the body of the request.\n","parameters":[{"schema":{"type":"string"},"name":"sessionToken","description":"Session authentication token.","in":"header","required":true}],"tags":["Streams"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stream"}}}},"400":{"description":"Client error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized: Invalid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden: Caller lacks necessary entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdList"}}},"description":"List of (integer) User IDs of participants","required":true}}}},"components":{"schemas":{"Stream":{"type":"object","properties":{"id":{"type":"string"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}},"UserIdList":{"type":"array","items":{"type":"integer","format":"int64"}}}}}
```

* The calling user is implicitly included as a member of the instant message conversation.
* One other participant must be specified.
* If a user ID appears in the list multiple times, duplicates will be ignored.
* If there is an existing IM conversation with the specified participant, then the id of the existing stream will be returned.
* Use [Create IM non-inclusive](https://rest-api.symphony.com/main/streams-conversations/im-mim-endpoints/create-im-or-mim-admin) to exclude the calling user.

When calling this as an [OBO-enabled endpoint](https://rest-api.symphony.com/main/apps-on-behalf-of-obo), use the [OBO User Authenticate](https://rest-api.symphony.com/main/apps-on-behalf-of-obo/obo-rsa-user-authentication-by-user-id) token for `sessionToken`.

A user needs to have the entitlement `isExternalIMEnabled` if he wants to create a crosspod IM (User entitlements are set on Admin Portal).

External users must be connected with the caller before adding them.

> #### 📘 Overview of streams
>
> A stream is like a container for messages exchanged between two or more users via a given instant message (IM) or chat room. For more information, refer to [Overview of streams](https://docs.developers.symphony.com/building-bots-on-symphony/datafeed/overview-of-streams).