Contact lookup

Contact lookup shows details about a customer from your own system, such as a CRM or billing system, right beside the conversation. When a customer messages you, IconEngage asks your endpoint about them by phone number and shows the fields you choose in the inbox.

How it works

1. A customer starts a conversation with you.
2. IconEngage sends a signed request to your endpoint with the customer's WhatsApp number and name.
3. Your endpoint answers with JSON describing the customer.
4. IconEngage picks out the fields you mapped and shows them under External profile in the customer panel. Up to three of them can also show in the conversation header.

The lookup never holds up incoming messages. It runs in the background, and the panel fills in when the answer arrives.

A result stays fresh for 24 hours. After that, the panel marks it "over a day old", and the customer's next conversation looks them up again. If a lookup fails, the panel keeps the last good details. Results are deleted after 30 days.

Your organisation can have one contact lookup.

Before you start

You need an endpoint on your side that:

• has a public https:// address on port 443 (private and internal addresses are refused);
• accepts a POST and checks its signature (see below);
• answers with status 200 and a single JSON object of at most 64 KiB, within the timeout you set.

Set up the connection

1. Go to Settings › Contact lookup, or click Set up contact lookup in Settings › All integrations.
2. Under Connection, enter a Name, for example "CRM lookup".
3. Enter your Endpoint URL.
4. Set the Timeout, from 500 to 5000 ms.
5. Optionally, under Authentication header, enter a Header name (such as Authorization or X-Api-Key) and its Header value, if your endpoint checks a key. The value is encrypted and never shown again.
6. Make sure Look customers up is on.
7. Click Create the lookup. You may be asked to confirm your password or authenticator code.
8. Copy the Signing secret that appears, store it with your endpoint's configuration, and click I have copied it.

Check the signature

Every call carries an X-IconEngage-Signature header. Your endpoint should check it with your signing secret before answering, and refuse a timestamp more than five minutes old. The Checking the signature section on the page shows the exact format, an example request, and sample code in Node.js and Python.

When you rotate the secret, calls are signed with a new key ID from then on. Accept both key IDs on your side while you deploy the new secret.

Choose the fields to show

1. Under Test, choose A contact or A phone number (with the country code, digits only, for example 919812345678).
2. Click Run the test. IconEngage calls your endpoint once, exactly as a real lookup does, and shows Your endpoint's answer.
3. Click a value in the answer to add it as a field. You can also click Add a field under Fields in the customer panel and type the path yourself.
4. For each field, set:
   • Label: what the panel calls it (up to 60 characters).
   • JSON path: where the value is in the answer, for example customer.plan, orders[0].total or ["first name"].
   • Shown as: Text, Number, Amount (with a three-letter Currency such as INR), Date, Link, Email, Phone or Badge.
   • Show in header: tick this for up to three fields.
5. Reorder the fields by dragging them or using the move buttons.
6. Check How the customer panel will look, then click Save the fields.

You can have up to 30 fields. A change to the fields takes effect at once, even for customers already looked up. You can run up to 10 tests a minute.

See the results in the inbox

Open a conversation and look at the customer panel on the right. The External profile section shows your fields. While a lookup is running it says "Looking this contact up…". To fetch fresh details, click Refresh the external profile. You can refresh each contact once a minute.

If something goes wrong, the panel says so, for example "Your system did not answer in time" or "Your system returned nothing to show for this contact". A value that does not fit its type shows as "Can't be shown". For more on the panel, see The contact panel.

Check recent lookups

Recent lookups lists every call to your endpoint in the last 30 days: when it ran, why (Conversation opened, Refreshed or Test), the result (Answered, Failed or Timed out), the HTTP status, the time it took and any problem. The log never keeps the answer or the phone number.

Turn off or delete

• To pause lookups, switch Look customers up off and click Save the connection. Nothing is called, and the panel says lookups are off.
• To remove it, click Delete the lookup and confirm. Its secret, its header, every customer profile it fetched and its log are deleted.