Create Conversations

POST /conversations

To create a new group or to have a conversation with a user for the first time, you need to call this API to ensure that the conversation is created first.

Endpoint URL

 https://api.mixin.one/conversations

Authentication and options

Authorization	`Authorized`
Limitation	No limitation

Payload

{
  "category":        "'GROUP' or 'CONTACT'",
  "conversation_id": "Unique identifier, see below to generate.",
  "name":            "Group name, valid when category is 'GROUP', 512 characters at most",
  "participants":    "Member list '[{ user_id: UUID }]', up to 256 people.",
}

info

The conversations you created are conversations between your bot/dApp and regular Mixin Messenger users. You cannot use the user's access_token to create them. Please use the bot/dApp's token to create conversations

info

When the category is CONTACT, the value of participants should be an array with length equal to 1, and the value of user_id is the other party's user_id.

Example request

curl -i -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" https://api.mixin.one/conversations --data PAYLOAD

Responses
{
  "data": {
    "type":             "conversation",
    "conversation_id":  "928c5c40-769c-3e97-8387-fb1ae0645311",
    "creator_id":       "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
    "category":         "GROUP",
    "name":             "",
    "icon_url":         "",
    "announcement":     "",
    "created_at":       "2018-05-16T12:34:44.134238105Z",
    "code_id":          "d8244b92-30e9-44b5-bfb0-ce597c788125",
    "code_url":         "https://mixin.one/codes/d8244b92-30e9-44b5-bfb0-ce597c788125",
    "mute_until":       "2018-05-16T12:34:44.143010035Z",
    "participants": [
      {
        "type":     "participant",
        "user_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
        "role":     "OWNER",
        "created_at": "2018-05-16T12:34:44.134238105Z"
      },
      {
        "type":     "participant",
        "user_id":  "e8e5b807-fa8b-455a-8dfa-b189d28310ff",
        "role":     "",
        "created_at": "2018-05-16T12:34:44.149277666Z"
      },
      ...
    ],
    "participant_sessions": [
      {
        "user_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
        "session_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
      },
      ...
    ],
    "circles": [
      {
        "circle_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
        "conversation_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
        "user_id":  "8dcf823d-9eb3-4da2-8734-f0aad50c0da6",
        "created_at": "2018-05-16T12:34:44.149277666Z"
      },
      ...
    ]
  }
}

Generate Unique Conversation ID

Single chat: category = "CONTACT"

The unique identification of the session is generated according to both parties, in Go:

func UniqueConversationId(userId, recipientId string) string {
  minId, maxId := userId, recipientId
  if strings.Compare(userId, recipientId) > 0 {
    maxId, minId = userId, recipientId
  }
  h := md5.New()
  io.WriteString(h, minId)
  io.WriteString(h, maxId)
  sum := h.Sum(nil)
  sum[6] = (sum[6] & 0x0f) | 0x30
  sum[8] = (sum[8] & 0x3f) | 0x80
  return uuid.FromBytesOrNil(sum).String()
}

Group chat: category = "GROUP"

golang
uuid.NewV4().String()

swift

UUID().uuidString.lowercased()

Note that UUID strings are unexceptionally converted to lowercase

POST /conversations​