> This page is for Omni Channel. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.hams.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server. # Pre-call context > The pre-call context endpoint returns the contact, the conversation, and the recent messages of a customer as a flat map. 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](/omni-channel/api/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`. ```bash 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: ```json { "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_` | 1 key for each custom attribute of the contact | | `contact_additional_attributes_` | 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_` | 1 key for each custom attribute of the conversation | | `conversation_additional_attributes_` | 1 key for each additional attribute of the conversation | > **Warning** > > 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](/omni-channel/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: ` 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](/omni-channel/api/errors). | ## Related * [Conversations](/omni-channel/api/conversations) * [Contacts](/omni-channel/api/contacts) * [Workflows](/omni-channel/workflows) * [Errors](/omni-channel/api/errors)