Matchai Docs

Send a messageComing soon

Sends a message, with files if you like, in the account holder’s name.

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

Coming soon. Sends a message, with files if you like, in the account holder’s name. Recipients see which app sent it. Send the exact text the person saw; never rewrite a draft they approved. In a conversation that runs by text message, the message goes out by text. Only messages that go out by text spend Energy; messages within Matchai do not.

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.

Spends Matchai Energy. Returns 402 without doing anything when the account does not have enough Energy, or when this connection reached the Energy limit the account holder set for it.

Scopes: messages:send

Pricing: Included with the connection, and spends Matchai Energy.

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

Path Parameters

conversation_id*string

Conversation id.

Length1 <= length <= 64

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

Sends in your name. Write it in the voice of the person whose account this is. Needs text, document_ids, or both.

text*unknown
document_ids?array<>

Files to send with it.

Items1 <= items <= 5
reply_to_message_id?string

Reply to this message.

Length1 <= length <= 64

Response Body

The message.

application/json
  1. response
id*string

Message id.

Length1 <= length <= 64
conversation_id*string

Conversation id.

Length1 <= length <= 64
type*string
Value in"text""image""file""audio""video""location""gif""system"
text*string

The text. Empty for a message that is only an attachment.

sender*

A person as they appear in a conversation or on an appointment.

from_you*boolean

Sent by the account this connection acts for.

sent_via*
reply_to_message_id?|

The message this replies to.

Length1 <= length <= 64
attachments*array<>

Files sent with it.

delivery*
sent_at*string

Sent.

Formatdate-time
edited_at?|

Last edited.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/conversations/string/messages' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "text": null}'
Example Response
{  "id": "string",  "conversation_id": "string",  "type": "text",  "text": "string",  "sender": {    "user_id": "string",    "contact_id": "string",    "display_name": "string",    "avatar_url": "http://example.com"  },  "from_you": true,  "sent_via": {    "kind": "person",    "app_name": "string"  },  "reply_to_message_id": "string",  "attachments": [    {      "document_id": "string",      "name": "string",      "mime_type": "string",      "size_bytes": 0    }  ],  "delivery": {    "channel": "matchai",    "state": "sent"  },  "sent_at": "2019-08-24T14:15:22Z",  "edited_at": "2019-08-24T14:15:22Z"}