Pre-call context | Hams AI Docs

The pre-call context endpoint gives an external voice agent what it must know about a customer before a call. It returns the contact, the latest conversation, the recent messages, and a text summary. All values are strings in 1 flat map, so a voice runtime can use each key as a template variable.

The endpoint only reads data. It does not create a contact or a conversation. It takes the same API key as the other developer endpoints. See Quickstart.

GET /api/v1/accounts/{account_id}/developer/precall_context

Find the customer

Give 1 of these query parameters. If the request has more than 1, the API reads them in this order and ignores the others.

Parameter	Meaning
`conversation_id`	The conversation number in the dashboard URL (`display_id`). The API uses this conversation and its contact
`contact_id`	The id of the contact. The API uses the conversation of the contact with the most recent activity, in any inbox
`phone_number`	The phone number of the contact, in E.164 format. The API adds the `+` if it is not there. It then uses the conversation of the contact with the most recent activity

In a query string, a + becomes a space. The API reads a number with a space or with no + as a number with a +. To send the +, you can also encode it as %2B.

curl -G https://omni-channel.hams.ai/api/v1/accounts/1/developer/precall_context \
  -H "api_access_token: $HAMS_TOKEN" \
  --data-urlencode "phone_number=+971500000000"

Response

The API answers 200 with a flat map of strings:

{
  "contact_id": "42",
  "contact_name": "Katherine Johnson",
  "contact_email": "katherine@example.com",
  "contact_phone_number": "+971500000000",
  "contact_identifier": "cust_9931",
  "contact_contact_type": "customer",
  "contact_custom_attributes_plan": "pro",
  "contact_additional_attributes_city": "Dubai",
  "conversation_id": "5821",
  "conversation_display_id": "1234",
  "conversation_inbox_id": "5",
  "conversation_contact_id": "42",
  "conversation_status": "open",
  "conversation_priority": "",
  "conversation_label_list": "vip, refund",
  "conversation_custom_attributes_order_id": "121212",
  "messages": "user: Where is my order?\nassistant: It is on its way.",
  "summary": "# Current Conversation Context\n- Conversation ID: 1234\n- Contact ID: 42\n- Status: open\n- Priority: None\n- Labels: vip, refund\n- order_id: 121212\n# Contact Information\n- Contact ID: 42\n- Name: Katherine Johnson\n- Email: katherine@example.com\n- Phone: +971500000000\n- Identifier: cust_9931\n- Type: customer\n- plan: pro\n- city: Dubai"
}

Contact keys

Key	Value
`contact_id`	The id of the contact
`contact_name`	The name of the contact
`contact_email`	The email address
`contact_phone_number`	The phone number
`contact_identifier`	Your own id for the contact
`contact_contact_type`	`visitor`, `lead`, or `customer`
`contact_custom_attributes_<key>`	1 key for each custom attribute of the contact
`contact_additional_attributes_<key>`	1 key for each additional attribute of the contact, for example `city`

Conversation keys

Key	Value
`conversation_id`	The internal `id` of the conversation. It is not the number in the dashboard URL
`conversation_display_id`	The conversation number in the dashboard URL
`conversation_inbox_id`	The id of the inbox
`conversation_contact_id`	The id of the contact
`conversation_status`	`open`, `resolved`, `pending`, or `snoozed`
`conversation_priority`	`urgent`, `high`, `medium`, `low`, or an empty string
`conversation_label_list`	The labels, with a comma and a space between them
`conversation_custom_attributes_<key>`	1 key for each custom attribute of the conversation
`conversation_additional_attributes_<key>`	1 key for each additional attribute of the conversation

Do not send the conversation_id of the response back to the other developer endpoints. It is the internal id. The other developer endpoints take the dashboard number, which is in conversation_display_id. The workflow trigger and the workflow webhook take the internal id. See Workflows.

If the contact has no conversation, the response has no conversation_* keys, and messages is an empty string.

Rules for all keys

A value that is empty in Hams is an empty string.
A nested object adds its keys to the name, with an underscore. For example, social_profiles.facebook becomes contact_additional_attributes_social_profiles_facebook.
A list becomes 1 string, with a comma and a space between the items.
An empty object adds no keys. For example, a contact with no custom attributes has no contact_custom_attributes_* keys.

Messages

messages has 1 line for each message, oldest first. A line starts with user: for a message from the customer and assistant: for a message to the customer. It includes the last 100 messages, up to 40,000 characters. Private notes, activity lines, and failed calls are not in it. A call shows its details and its transcript. A line assistant: <conversation_boundary status="resolved" /> marks the end of an earlier resolved conversation cycle.

Summary

summary is the same context as the other keys, as a Markdown text. It has a # Current Conversation Context part when there is a conversation, and a # Contact Information part. The AI agent of Hams gets the same context in its prompt. You can put it into the prompt of your voice agent as it is.

Errors

Status	Body	Cause
`422`	`{"error": "identifier_required", ...}`	The request had none of `conversation_id`, `contact_id`, or `phone_number`.
`422`	`{"error": "invalid_phone_number", ...}`	The number is not in E.164 format, also after the API adds the `+`.
`404`	`{"error": "not_found", ...}`	No conversation, contact, or phone number in this account matches.
`401`	`{"error": "..."}`	The key is not valid for this account. See Errors.