Matchai Docs

Start a conversationComing soon

Opens a conversation with a contact, or invites someone who is not on Matchai by email or by a link you pass on, and sends first_message.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
POST
/conversations

Coming soon. Opens a conversation with a contact, or invites someone who is not on Matchai by email or by a link you pass on, and sends first_message. When a conversation with that person already exists, the message goes into it.

Final action. When the connection is set to Ask me, this call returns 202 with an approval_url and does nothing until the account holder approves it in Matchai; Matchai then performs it exactly as sent and sends approval.resolved. When the connection is set to Allowed, it runs straight away.

Scopes: messages:send

Pricing: Included with the connection.

Authorization

headerAuthorizationBearer <matchai_<base62>>

A personal API key, sent as Authorization: Bearer matchai_…. Create keys in Matchai under Settings → Connectors → Advanced (for developers). A key starts with matchai_ followed by letters and digits, carries the scopes chosen when it was created, and can be revoked at any time. Keys reach only the account that created them: to serve other professionals, use Connect with Matchai.

Scope: messages:send

Header Parameters

Idempotency-Key?string

A unique string (a UUID works). Retrying with the same key within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 255

Request Body

application/json
  1. body

Opens a conversation with exactly one of contact_id, email or phone. Someone who is not on Matchai is invited: an email invitation really sends and quotes first_message; a phone number is never texted, it becomes an invitation link in invitation.accept_url for you to pass on.

contact_id*unknown
email?string

Someone not in your contacts.

Formatemail
phone?string

Someone not in your contacts. Any country.

Lengthlength <= 40
name?string

Their name, for someone not in your contacts.

Lengthlength <= 120
contact_type?ContactType

lead: a potential customer. client: a customer you have worked with. professional: a peer, such as another broker, a notary or a lender.

Value in"lead""client""professional"
first_message?string

What to say first.

Lengthlength <= 2000

Response Body

The conversation.

application/json
  1. response
conversation*
created*boolean

False when you already had a conversation with this person; the first message went into it.

invitation?|null
Example Request
curl -X POST 'https://api.matchai.co/v1/conversations' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "contact_id": null}'
Example Response
{  "conversation": {    "id": "string",    "type": "direct",    "channel": "matchai",    "name": "string",    "participants": [      {        "user_id": "string",        "contact_id": "string",        "display_name": "string",        "avatar_url": "http://example.com"      }    ],    "context": {      "listing_id": "string",      "contact_id": "string",      "project_id": "string",      "team_id": "string"    },    "last_message": {      "id": "string",      "preview": "string",      "sender_user_id": "string",      "sent_at": "2019-08-24T14:15:22Z"    },    "unread_count": 0,    "archived": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "created": true,  "invitation": {    "id": "string",    "target": {      "type": "team",      "id": "string",      "name": "string"    },    "role": "owner",    "direction": "sent",    "status": "pending",    "invited": {      "display_name": "string",      "email": "user@example.com",      "phone": "string"    },    "invited_by": {      "user_id": "string",      "display_name": "string"    },    "delivery": {      "channel": "email",      "state": "pending"    },    "accept_url": "http://example.com",    "expires_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "responded_at": "2019-08-24T14:15:22Z"  }}