Inbox API

Every channel in one inbox — conversations, replies, teams and who answers.

Module code inbox · 63 actions · 22 data models · 45 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: inbox (everything), inbox:read (read only) or inbox:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

inbox.add_participant

Add a follower — Lets somebody follow a conversation without being assigned it.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.add_participant

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.participant_added

What it writes: conversation_participant (insert) — Adds the follower

curl -X POST https://app.getera.io/api/v1/conversation_participants/actions/add_participant \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CONVERSATION_ID","userId":"USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.participant_added"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversationParticipants.addParticipant({
  id: "CONVERSATION_ID",
  userId: "USER_ID"
})

era conversation_participants add_participant \
  --id "CONVERSATION_ID" \
  --user-id "USER_ID"

{
  "name": "era__inbox__add_participant",
  "arguments": {
    "id": "CONVERSATION_ID",
    "userId": "USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, not_a_member, already_participating · 429 slow down

inbox.add_private_note

Add a private note — Leaves a note on the conversation that the customer never sees.

Needs inbox:comment · changes data

• Canonical address: POST /api/v1/actions/inbox.add_private_note

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.note_added, inbox.mentioned, inbox.user_mentioned

What it writes: message (insert) — Writes the private note; message_attachment (insert) — Attaches files; conversation (update) — Touches the activity clock; conversation_mention (upsert) — Records who was mentioned; conversation_participant (insert) — Makes the people mentioned followers

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/add_private_note \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"content":"Message"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.note_added",
    "inbox.mentioned",
    "inbox.user_mentioned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.addPrivateNote("CONVERSATION_ID", {
  content: "Message"
})

era conversations add_private_note CONVERSATION_ID \
  --content "Message"

{
  "name": "era__inbox__add_private_note",
  "arguments": {
    "conversationId": "CONVERSATION_ID",
    "content": "Message"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:comment · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, empty_message, too_many_attachments, too_many_messages, canned_response_not_found, mentioned_cannot_read · 429 slow down

inbox.apply_sla

Apply an SLA — Measures a conversation against a response-time policy.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.apply_sla

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.sla_applied, inbox.sla_missed

What it writes: applied_sla (insert) — Starts measuring; sla_event (insert) — Records a target already missed

curl -X POST https://app.getera.io/api/v1/applied_slas/actions/apply_sla \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"conversationId":"CONVERSATION_ID","policyId":"SLA_POLICY_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.sla_applied",
    "inbox.sla_missed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.appliedSlas.applySla({
  conversationId: "CONVERSATION_ID",
  policyId: "SLA_POLICY_ID"
})

era applied_slas apply_sla \
  --conversation-id "CONVERSATION_ID" \
  --policy-id "SLA_POLICY_ID"

{
  "name": "era__inbox__apply_sla",
  "arguments": {
    "conversationId": "CONVERSATION_ID",
    "policyId": "SLA_POLICY_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, sla_policy_not_found, sla_already_applied · 429 slow down

inbox.assign

Assign a conversation — Gives the conversation to somebody who works that inbox, or returns it to the queue.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.assign

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.assigned

What it writes: conversation (update) — Sets the assignee

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/assign \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"userId":"USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.assigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.assign("CONVERSATION_ID", {
  userId: "USER_ID"
})

era conversations assign CONVERSATION_ID \
  --user-id "USER_ID"

{
  "name": "era__inbox__assign",
  "arguments": {
    "id": "CONVERSATION_ID",
    "userId": "USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, not_a_member, not_an_inbox_member, not_in_conversation_team · 429 slow down

inbox.assign_bot

Hand a conversation to a bot — Gives the conversation to a bot connected to that inbox, or takes it back.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.assign_bot

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.assigned, inbox.bot_handoff

What it writes: conversation (update) — Sets or clears the bot; reporting_event (insert) — Writes the report clock reading (sql/126)

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/assign_bot \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agentBotId":"AGENT_BOT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.assigned",
    "inbox.bot_handoff"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.assignBot("CONVERSATION_ID", {
  agentBotId: "AGENT_BOT_ID"
})

era conversations assign_bot CONVERSATION_ID \
  --agent-bot-id "AGENT_BOT_ID"

{
  "name": "era__inbox__assign_bot",
  "arguments": {
    "id": "CONVERSATION_ID",
    "agentBotId": "AGENT_BOT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, bot_not_on_inbox · 429 slow down

inbox.assign_era

Give a conversation to Era — Era drafts every reply as a private note, or answers — a reply still waits for your approval unless you allowed it.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.assign_era

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.era_assigned

What it writes: conversation (update) — Gives the conversation to Era, or takes it back

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/assign_era \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"draft"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.era_assigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.assignEra("CONVERSATION_ID", {
  mode: "draft"
})

era conversations assign_era CONVERSATION_ID \
  --mode "draft"

{
  "name": "era__inbox__assign_era",
  "arguments": {
    "id": "CONVERSATION_ID",
    "mode": "draft"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, era_off · 429 slow down

inbox.assign_team

Move a conversation to a team — Routes the conversation to a team, dropping an assignee who is not in it.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.assign_team

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.team_assigned

What it writes: conversation (update) — Sets the team

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/assign_team \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"teamId":"TEAM_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.team_assigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.assignTeam("CONVERSATION_ID", {
  teamId: "TEAM_ID"
})

era conversations assign_team CONVERSATION_ID \
  --team-id "TEAM_ID"

{
  "name": "era__inbox__assign_team",
  "arguments": {
    "id": "CONVERSATION_ID",
    "teamId": "TEAM_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, team_not_found · 429 slow down

inbox.auto_assign

Assign automatically — Picks the next agent by the inbox’s routing rule, within their fair share.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.auto_assign

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.assigned

What it writes: conversation (update) — Sets the assignee; inbox_member (update) — Moves the agent to the back of the queue

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/auto_assign \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.assigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.autoAssign("CONVERSATION_ID")

era conversations auto_assign CONVERSATION_ID

{
  "name": "era__inbox__auto_assign",
  "arguments": {
    "id": "CONVERSATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, inbox_not_found, auto_assignment_off, policy_disabled · 429 slow down

inbox.bot_reply

A bot replies — What a bot says to the customer, through the bot API.

Needs inbox:handle · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/inbox.bot_reply

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.message_sent

What it writes: message (insert) — Writes the bot’s message, queued for delivery; conversation (update) — Clears the waiting clock

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/bot_reply \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agentBotId":"AGENT_BOT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.message_sent"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.botReply("CONVERSATION_ID", {
  agentBotId: "AGENT_BOT_ID"
})

era conversations bot_reply CONVERSATION_ID \
  --agent-bot-id "AGENT_BOT_ID"

{
  "name": "era__inbox__bot_reply",
  "arguments": {
    "conversationId": "CONVERSATION_ID",
    "agentBotId": "AGENT_BOT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agent_bot_not_found, conversation_not_found, bot_not_on_inbox, unsupported_content_type, empty_message, conversation_resolved, too_many_messages · 429 slow down

inbox.bot_set_status

A bot hands over or resolves — The bot passes the conversation to people, or closes it.

Needs inbox:handle · changes data

• Canonical address: POST /api/v1/actions/inbox.bot_set_status

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.bot_handoff, inbox.resolved, inbox.message_sent

What it writes: conversation (update) — Opens it for people, or resolves it; message (insert) — The rating request, when resolving asks for one; reporting_event (insert) — Writes the report clock reading (sql/126)

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/bot_set_status \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agentBotId":"AGENT_BOT_ID","status":"open"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.bot_handoff",
    "inbox.resolved",
    "inbox.message_sent"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.botSetStatus("CONVERSATION_ID", {
  agentBotId: "AGENT_BOT_ID",
  status: "open"
})

era conversations bot_set_status CONVERSATION_ID \
  --agent-bot-id "AGENT_BOT_ID" \
  --status "open"

{
  "name": "era__inbox__bot_set_status",
  "arguments": {
    "conversationId": "CONVERSATION_ID",
    "agentBotId": "AGENT_BOT_ID",
    "status": "open"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agent_bot_not_found, conversation_not_found, bot_not_on_inbox, already_open, already_resolved · 429 slow down

inbox.bulk_update

Change several conversations — Resolves, snoozes, assigns, routes or ranks a selection at once — all or none.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.bulk_update

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.assigned, inbox.team_assigned, inbox.resolved, inbox.reopened, inbox.snoozed, inbox.priority_changed, inbox.message_sent

What it writes: conversation (update) — Applies the change to each conversation; inbox_member (update) — Moves an assignee to the back of the queue; message (insert) — A rating request, when resolving asks for one; reporting_event (insert) — Writes the report clock reading (sql/126)

curl -X POST https://app.getera.io/api/v1/messages/actions/bulk_update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ids":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.assigned",
    "inbox.team_assigned",
    "inbox.resolved",
    "inbox.reopened",
    "inbox.snoozed",
    "inbox.priority_changed",
    "inbox.message_sent"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.messages.bulkUpdate({
  ids: {}
})

era messages bulk_update --data '{"ids":{}}'

{
  "name": "era__inbox__bulk_update",
  "arguments": {
    "ids": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_selection, nothing_to_change · 429 slow down

inbox.change_customer

Move a conversation to another person — Corrects who a conversation is with, keeping the channel address it arrived on.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.change_customer

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.customer_changed

What it writes: conversation (update) — Repoints the conversation

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/change_customer \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customerId":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.customer_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.changeCustomer("CONVERSATION_ID", {
  customerId: "CUSTOMER_ID"
})

era conversations change_customer CONVERSATION_ID \
  --customer-id "CUSTOMER_ID"

{
  "name": "era__inbox__change_customer",
  "arguments": {
    "id": "CONVERSATION_ID",
    "customerId": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, customer_not_found, customer_archived · 429 slow down

inbox.create_inbox

Connect a channel — Opens a new inbox on one of the supported channels.

Needs inbox:manage · changes data

• REST alias: POST /api/v1/inboxes
• Canonical address: POST /api/v1/actions/inbox.create_inbox

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.channel_connected

What it writes: inbox (insert) — Opens the channel; inbox_member (insert) — Records who works it

curl -X POST https://app.getera.io/api/v1/inboxes/actions/create_inbox \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name","channelType":"web_widget"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.channel_connected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.inboxes.create({
  name: "Name",
  channelType: "web_widget"
})

era inboxes create \
  --name "Name" \
  --channel-type "web_widget"

{
  "name": "era__inbox__create_inbox",
  "arguments": {
    "name": "Name",
    "channelType": "web_widget"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 identifier_taken, channel_config_incomplete, not_a_member, mailbox_connection_required, mailbox_not_mail_app, connection_not_usable, connection_not_found, connection_inactive · 429 slow down

inbox.deactivate_inbox

Take a channel out of service — Stops an inbox taking new conversations, keeping everything it already holds.

Needs inbox:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/inbox.deactivate_inbox

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.channel_deactivated

What it writes: inbox (update) — Marks the channel inactive

curl -X POST https://app.getera.io/api/v1/inboxes/INBOXE_ID/actions/deactivate_inbox \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.channel_deactivated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.inboxes.deactivateInbox("INBOXE_ID")

era inboxes deactivate_inbox INBOXE_ID

{
  "name": "era__inbox__deactivate_inbox",
  "arguments": {
    "id": "INBOXE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 inbox_not_found, inbox_has_open_conversations · 429 slow down

inbox.delete_agent_bot

Remove a bot — Removes the bot; conversations it was holding go to the team.

Needs inbox:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/agent_bots/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_agent_bot

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.agent_bot_changed

What it writes: conversation (update) — Hands its pending conversations to people; agent_bot (delete) — Removes the bot and its inbox bindings

curl -X POST https://app.getera.io/api/v1/agent_bots/AGENT_BOT_ID/actions/delete_agent_bot \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.agent_bot_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.agentBots.deleteAgentBot("AGENT_BOT_ID")

era agent_bots delete_agent_bot AGENT_BOT_ID

{
  "name": "era__inbox__delete_agent_bot",
  "arguments": {
    "id": "AGENT_BOT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 agent_bot_not_found · 429 slow down

inbox.delete_canned_response

Delete a saved reply — Removes a shortcut from the composer.

Needs inbox:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/canned_responses/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_canned_response

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.canned_response_changed

What it writes: canned_response (delete) — Removes the saved reply

curl -X POST https://app.getera.io/api/v1/canned_responses/CANNED_RESPONSE_ID/actions/delete_canned_response \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.canned_response_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.cannedResponses.deleteCannedResponse("CANNED_RESPONSE_ID")

era canned_responses delete_canned_response CANNED_RESPONSE_ID

{
  "name": "era__inbox__delete_canned_response",
  "arguments": {
    "id": "CANNED_RESPONSE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 canned_response_not_found · 429 slow down

inbox.delete_macro

Delete a macro — Removes a macro.

Needs inbox:write · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/macros/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_macro

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.macro_changed

What it writes: macro (delete) — Removes the macro

curl -X POST https://app.getera.io/api/v1/macros/MACRO_ID/actions/delete_macro \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.macro_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.macros.deleteMacro("MACRO_ID")

era macros delete_macro MACRO_ID

{
  "name": "era__inbox__delete_macro",
  "arguments": {
    "id": "MACRO_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 macro_not_found, not_macro_owner · 429 slow down

inbox.delete_message

Delete a message — Removes a message from the thread, keeping the row for the audit trail.

Needs inbox:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/messages/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_message

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.message_deleted

What it writes: message (update) — Writes the tombstone

curl -X POST https://app.getera.io/api/v1/messages/MESSAGE_ID/actions/delete_message \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.message_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.messages.deleteMessage("MESSAGE_ID")

era messages delete_message MESSAGE_ID

{
  "name": "era__inbox__delete_message",
  "arguments": {
    "id": "MESSAGE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 message_not_found · 429 slow down

inbox.delete_sla_policy

Delete an SLA policy — Removes a policy nothing has been measured against.

Needs inbox:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/sla_policies/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_sla_policy

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.sla_policy_changed

What it writes: sla_policy (delete) — Deletes the policy

curl -X POST https://app.getera.io/api/v1/sla_policies/SLA_POLICY_ID/actions/delete_sla_policy \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.sla_policy_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.slaPolicies.deleteSlaPolicy("SLA_POLICY_ID")

era sla_policies delete_sla_policy SLA_POLICY_ID

{
  "name": "era__inbox__delete_sla_policy",
  "arguments": {
    "id": "SLA_POLICY_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sla_policy_not_found, sla_policy_in_use · 429 slow down

inbox.delete_team

Delete a team — Removes a team, leaving its conversations without one.

Needs inbox:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/teams/{id}
• Canonical address: POST /api/v1/actions/inbox.delete_team

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.team_changed

What it writes: team (delete) — Removes the team

curl -X POST https://app.getera.io/api/v1/teams/TEAM_ID/actions/delete_team \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"force":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.team_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.teams.deleteTeam("TEAM_ID", {
  force: true
})

era teams delete_team TEAM_ID \
  --force true

{
  "name": "era__inbox__delete_team",
  "arguments": {
    "id": "TEAM_ID",
    "force": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 team_not_found, team_has_open_conversations · 429 slow down

inbox.edit_message

Edit a message — Corrects a message you sent.

Needs inbox:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/inbox.edit_message

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.message_edited

What it writes: message (update) — Rewrites the message and marks it edited

curl -X POST https://app.getera.io/api/v1/messages/MESSAGE_ID/actions/edit_message \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"content":"Message"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.message_edited"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.messages.editMessage("MESSAGE_ID", {
  content: "Message"
})

era messages edit_message MESSAGE_ID \
  --content "Message"

{
  "name": "era__inbox__edit_message",
  "arguments": {
    "id": "MESSAGE_ID",
    "content": "Message"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 message_not_found, message_not_editable, empty_message · 429 slow down

inbox.evaluate_sla

Check an SLA — Records the targets a conversation has missed, and settles hit or missed once it is resolved.

Needs inbox:handle · changes data

• Canonical address: POST /api/v1/actions/inbox.evaluate_sla

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.sla_missed, inbox.sla_closed

What it writes: applied_sla (update) — Writes the status and the next deadline; sla_event (insert) — One row per missed target

curl -X POST https://app.getera.io/api/v1/applied_slas/APPLIED_SLA_ID/actions/evaluate_sla \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.sla_missed",
    "inbox.sla_closed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.appliedSlas.evaluateSla("APPLIED_SLA_ID")

era applied_slas evaluate_sla APPLIED_SLA_ID

{
  "name": "era__inbox__evaluate_sla",
  "arguments": {
    "id": "APPLIED_SLA_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 applied_sla_not_found · 429 slow down

inbox.ingest

Take in an arriving message — Files a message that came in on a channel, opening the conversation if it is new.

Needs inbox:handle · changes data

• Canonical address: POST /api/v1/actions/inbox.ingest

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.message_received, inbox.conversation_opened, inbox.reopened, inbox.message_sent

What it writes: conversation (upsert) — Finds the thread, or opens a new one; message (insert) — Files what arrived; message_attachment (insert) — Files what came with it; reporting_event (insert) — Writes the report clock reading (sql/126)

curl -X POST https://app.getera.io/api/v1/conversations/actions/ingest \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inboxId":"INBOX_ID","customerId":"CUSTOMER_ID","sourceId":"The provider’s id for this message"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.message_received",
    "inbox.conversation_opened",
    "inbox.reopened",
    "inbox.message_sent"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.ingest({
  inboxId: "INBOX_ID",
  customerId: "CUSTOMER_ID",
  sourceId: "The provider’s id for this message"
})

era conversations ingest \
  --inbox-id "INBOX_ID" \
  --customer-id "CUSTOMER_ID" \
  --source-id "The provider’s id for this message"

{
  "name": "era__inbox__ingest",
  "arguments": {
    "inboxId": "INBOX_ID",
    "customerId": "CUSTOMER_ID",
    "sourceId": "The provider’s id for this message"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 inbox_not_found, inbox_inactive, no_source_id, empty_message, malformed_message, duplicate_message, customer_not_found, customer_archived · 429 slow down

inbox.mark_read

Mark read — Records that the thread has been seen.

Needs inbox:read · changes data

• Canonical address: POST /api/v1/actions/inbox.mark_read

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: conversation (update) — Stamps the read marks

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/mark_read \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.markRead("CONVERSATION_ID")

era conversations mark_read CONVERSATION_ID

{
  "name": "era__inbox__mark_read",
  "arguments": {
    "id": "CONVERSATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found · 429 slow down

inbox.mark_unread

Mark unread — Moves the read marker behind the first incoming message so the conversation returns to the unread queue.

Needs inbox:read · changes data

• Canonical address: POST /api/v1/actions/inbox.mark_unread

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: conversation (update) — Moves the read marker back

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/mark_unread \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": []
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.markUnread("CONVERSATION_ID")

era conversations mark_unread CONVERSATION_ID

{
  "name": "era__inbox__mark_unread",
  "arguments": {
    "id": "CONVERSATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found · 429 slow down

inbox.mute

Mute — Resolves the conversation and files what the person sends next without reopening it.

Needs inbox:write · changes data

• Canonical address: POST /api/v1/actions/inbox.mute

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: inbox.muted

What it writes: conversation (update) — Mutes and resolves it; reporting_event (insert) — Writes the report clock reading (sql/126)

curl -X POST https://app.getera.io/api/v1/conversations/CONVERSATION_ID/actions/mute \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "inbox.muted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.conversations.mute("CONVERSATION_ID")

era conversations mute CONVERSATION_ID

{
  "name": "era__inbox__mute",
  "arguments": {
    "id": "CONVERSATION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold inbox:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 conversation_not_found, already_muted · 429 slow down

inbox.open_conversation

Open a conversation — Starts a conversation with somebody on one of your channels.

Needs inbox:write · changes data

• REST alias: POST /api/v1/conversations
• Canonical address: POST /api/v1/actions/inbox.open_conversation

Input