Identity: messages

Send a message to a contact as this identity

POST /v1/identities/{slug}/messages · operation sendMessage

Requires the batondeck:messages:send permission (action message:send).

Refused while the workspace is suspended or on deletion hold.

Accepts an Idempotency-Key header. A repeat within 24 hours returns the first answer; the same key with different arguments is refused with idempotency_mismatch.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
Idempotency-Key	header	string		Repeat this value to retry the call without repeating its effect.

Request body (application/json)

Field	Type	Required	Notes
fingerprint	string	yes	≥ 1 chars
text	string	yes	≥ 1 chars, ≤ 16384 chars
thread_id	string		≤ 128 chars
msg_id	string		≤ 128 chars

Request schema

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "minLength": 1
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "thread_id": {
      "type": "string",
      "maxLength": 128
    },
    "msg_id": {
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "fingerprint",
    "text"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
201	Send a message to a contact as this identity
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.
422	That Idempotency-Key was used with different arguments.
429	This identity’s outbound budget (HDTP §12: 1 call a second per contact with a burst of 10, the identity’s aggregate, 20 an hour to strangers), or the peer’s own, refused the call; retry_after and Retry-After say when to try again.

201 response schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "thread_id": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "message_id",
    "thread_id"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/identities/:slug/messages' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Try again now to deliver an outbound text message that has not arrived (pending, or given up on)

POST /v1/identities/{slug}/messages/{id}/retry · operation retryMessage

Requires the batondeck:messages:send permission (action message:send).

Refused while the workspace is suspended or on deletion hold.

Accepts an Idempotency-Key header. A repeat within 24 hours returns the first answer; the same key with different arguments is refused with idempotency_mismatch.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
id	path	string	yes
Idempotency-Key	header	string		Repeat this value to retry the call without repeating its effect.

Responses

Status	Meaning
200	Try again now to deliver an outbound text message that has not arrived (pending, or given up on)
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.
422	That Idempotency-Key was used with different arguments.
429	This identity’s outbound budget (HDTP §12: 1 call a second per contact with a burst of 10, the identity’s aggregate, 20 an hour to strangers), or the peer’s own, refused the call; retry_after and Retry-After say when to try again.

200 response schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "thread_id": {
      "type": "string"
    },
    "attempts": {
      "type": "number"
    },
    "last_refusal": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "message_id",
    "thread_id",
    "attempts",
    "last_refusal"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/identities/:slug/messages/:id/retry' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"