Skip to content
Beeper Developer Docs
Download Beeper
API Reference
Chats

Create or start a chat

client.Chats.New(ctx, body) (*ChatNewResponse, error)
POST/v1/chats

Create a single/group chat (mode=‘create’) or start a direct chat from merged user data (mode=‘start’).

ParametersExpand Collapse
body ChatNewParams
Params param.Field[ChatNewParamsParamsUnion]Optional
type ChatNewParamsParamsObject struct{…}
AccountID string

Account to create or start the chat on.

Mode string

Operation mode. Use ‘start’ to resolve a user/contact and start a direct chat.

User ChatNewParamsParamsObjectUser

Merged user-like contact payload used to resolve the best identifier.

ID stringOptional

Known user ID when available.

Email stringOptional

Email candidate.

FullName stringOptional

Display name hint used for ranking only.

PhoneNumber stringOptional

Phone number candidate (E.164 preferred).

Username stringOptional

Username/handle candidate.

AllowInvite boolOptional

Whether invite-based DM creation is allowed when required by the platform. Used for mode=‘start’.

MessageText stringOptional

Optional first message content if the platform requires it to create the chat.

type ChatNewParamsParamsObject struct{…}
AccountID string

Account to create or start the chat on.

ParticipantIDs []string

User IDs to include in the new chat.

Type string

‘single’ requires exactly one participantID; ‘group’ supports multiple participants and optional title.

One of the following:
const ChatNewParamsParamsObjectTypeSingle ChatNewParamsParamsObjectType = "single"
const ChatNewParamsParamsObjectTypeGroup ChatNewParamsParamsObjectType = "group"
MessageText stringOptional

Optional first message content if the platform requires it to create the chat.

Mode stringOptional

Operation mode. Defaults to ‘create’ when omitted.

Title stringOptional

Optional title for group chats; ignored for single chats on most platforms.

ReturnsExpand Collapse
type ChatNewResponse struct{…}
ChatID string

Newly created chat ID.

Status ChatNewResponseStatusOptional

Only returned in start mode. ‘existing’ means an existing chat was reused; ‘created’ means a new chat was created.

One of the following:
const ChatNewResponseStatusExisting ChatNewResponseStatus = "existing"
const ChatNewResponseStatusCreated ChatNewResponseStatus = "created"

Create or start a chat

package main

import (
  "context"
  "fmt"

  "github.com/beeper/desktop-api-go"
  "github.com/beeper/desktop-api-go/option"
)

func main() {
  client := beeperdesktopapi.NewClient(
    option.WithAccessToken("My Access Token"),
  )
  chat, err := client.Chats.New(context.TODO(), beeperdesktopapi.ChatNewParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", chat.ChatID)
}

{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}
Returns Examples
{
  "chatID": "!NCdzlIaMjZUmvmvyHU:beeper.com",
  "status": "existing"
}