Start a dialog

Writes first to someone — what the New message button in Lalexi does — with you as the one who started it. Works on channels whose capabilities.can_start_dialog is true:

messenger channels — phone (or contact_id) and text; the message goes out from the connected account and the conversation appears in the workspace;
e-mail — email (or contact_id), subject and text;
WhatsApp Business — phone (or contact_id), an approved template of the channel, and text as the template's wording to show in the conversation.

Outcomes:

HTTP	body	meaning
201	`status: sent` with `conversation` and `message`	sent; `message` is `null` if it has not appeared in the conversation yet, both are `null` if it joined a conversation you may not open
202	`status: sent`, `warning: mirror_pending`	sent; the conversation will appear shortly
202	`status: unknown`	the outcome did not come back in time — the message may have been delivered; check before sending again
409	`duplicate`	the same text went to the same number from this channel less than 60 seconds ago
409	`message_limit_reached`	the workspace has used its message limit (`details.limit`, `details.used`)
503	`upstream_unavailable`	nothing was sent; retrying is safe

Supports Idempotency-Key — every outcome above, unknown included, is replayed for the same key and never sent twice. Limited to 20 starts a minute per token.

Authorization

personalToken

AuthorizationBearer <token>

Your personal access token from Profile → Access Token in Lalexi. It acts with exactly your role: what you may see and do in the workspace, and nothing more. Everything done with it is recorded as done by you.

In: header

Header Parameters

Idempotency-Key?string

Your key for this request (up to 255 characters). A repeat with the same key within 24 hours returns the first answer and sends nothing new; 409 idempotency_in_progress while the first one runs; 422 idempotency_key_reused for the same key with a different request.

Lengthlength <= 255

X-Workspace-Id?integer

The workspace to work in (an id from GET /me). Optional when you belong to a single workspace; required otherwise (400 workspace_required).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

channel_id*integer

A channel you work in whose capabilities.can_start_dialog is true.

phone?string

The recipient on messenger channels and WhatsApp Business — a phone number in any formatting (10–15 digits); on Telegram channels also a @username.

Lengthlength <= 64

email?string

The recipient on an e-mail channel.

Formatemail

contact_id?integer

Instead of phone / email — write to this contact (at its phone, or its e-mail on an e-mail channel).

text*string

Lengthlength <= 4096

subject?string

The subject line. Required on an e-mail channel.

template?

An approved WhatsApp Business template of the channel.

external_id?ExternalId

Your own id for the message, returned as external_id on it and in its webhooks.

Lengthlength <= 255

Response Body

`application/json`

curl -X POST "https://app.lalexi.com/v1/dialogs" \  -H "Idempotency-Key: crm-order-1042-confirmation" \  -H "X-Workspace-Id: 7" \  -H "Content-Type: application/json" \  -d '{    "channel_id": 12,    "phone": "+7 900 123-45-67",    "text": "Hello! This is Anna from the store."  }'

{
  "status": "sent",
  "conversation": {
    "id": 0,
    "status": "open",
    "priority": "low",
    "channel": {
      "id": 0,
      "name": "string",
      "type": "whatsapp"
    },
    "contact": {
      "id": 0,
      "name": "string",
      "phone": "string",
      "email": "string"
    },
    "assignee": {
      "id": 0,
      "name": "string"
    },
    "team": {
      "id": 0,
      "name": "string"
    },
    "labels": [
      "string"
    ],
    "custom_attributes": {},
    "snoozed_until": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "last_activity_at": "2019-08-24T14:15:22Z"
  },
  "message": {
    "id": 0,
    "conversation_id": 0,
    "type": "incoming",
    "text": "string",
    "deleted": true,
    "sender": {
      "type": "agent",
      "id": 0,
      "name": "string"
    },
    "status": "sent",
    "error_code": "message_limit_reached",
    "attachments": [
      {
        "id": 0,
        "type": "image",
        "url": "string",
        "file_name": "string",
        "size": 0,
        "content_type": "image/png"
      }
    ],
    "via": "api",
    "external_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "warning": "mirror_pending"
}

{
  "status": "sent",
  "conversation": null,
  "message": null,
  "warning": "mirror_pending"
}

{
  "error": {
    "code": "workspace_required",
    "message": "You belong to several workspaces: pass the X-Workspace-Id header."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "You are not allowed to do this."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found."
  }
}

{
  "error": {
    "code": "message_limit_reached",
    "message": "The workspace has used its message limit.",
    "details": {
      "limit": 1000,
      "used": 1000
    }
  }
}

{
  "error": {
    "code": "channel_reply_only",
    "message": "This channel can only answer people who wrote first."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in Retry-After."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side."
  }
}

{
  "error": {
    "code": "upstream_unavailable",
    "message": "The messaging service is unavailable. Nothing was sent; try again."
  }
}

Start a dialog

Authorization

Header Parameters

Request Body

Response Body

201application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

503application/json

Sent, the conversation will appear shortly

The outcome did not come back in time

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`