Integrations

Integrations send what happens in IconEngage to your other systems, and bring their records back in. You set them up in Settings › All integrations.

The directory

Go to Settings › All integrations. The page has three parts:

• Your connections: one row per connection, with its Connector, Health, State (Enabled or Disabled), how many Events it receives, and when it was last updated. Filter by Connector or Health, and click Open to manage one.
• Contact lookup: a card that opens Contact lookup, which shows details from your own system in the inbox.
• Available connectors: the connector types this release includes. You cannot add new types here; new connectors come with product releases.

Each connector card says what it can do:

Connectors you can use today

A Preview connector is built and tested against a test server, but is not yet turned on for real accounts. If you try to connect one, you see "This connector is not turned on for real accounts on this deployment yet."

Use Webhook to send IconEngage events to any HTTPS endpoint you run. Use REST service to connect your own API: it can send events, import records (customers, orders, products) and receive calls.

Connect a system

1. Go to Settings › All integrations.
2. Under Available connectors, click Connect on the connector you want.
3. In Details, enter a Name for the connection (only your team sees it), the Base URL (HTTPS and a public address only, with no username or password in it), and any Configuration fields the connector asks for.
4. Click Create connection. The connection is saved, disabled.
5. In Credentials, enter the values the connector needs, such as an API token or secret and a Signing secret, and click Save credentials. You may be asked to confirm your password or authenticator code.
6. On Finish, click Open the connection.

Credentials are encrypted and never shown again, not even to you. The connection page only says whether each one is Set or Not set, when it was set, and sometimes its last few characters. If you click Finish without credentials, the connection cannot be enabled until every required credential is set.

Set up and switch on a connection

A new connection does nothing until you choose its events and switch it on. Open it from Your connections. The Overview tab has these sections:

• Events: tick the IconEngage events it should receive, such as Message received, Conversation opened, Tag added, Field changed or Order placed, and click Save events. With nothing ticked, nothing is delivered.
• Configuration: click Edit to change the connector's settings.
• Credentials: click Set credentials or Replace credentials.
• Inbound URL (for connectors that receive): click Show URL or Copy URL and give it to the other system. The URL alone does not let anyone in; only calls signed with the signing secret are accepted.
• Health: last success, last failure and failures in a row.

Then:

1. Click Test connection. A test makes one call and writes nothing. You see how long the other system took to answer, or that it did not answer as expected.
2. Switch Enabled on.

Map fields

Open the Field map tab. Each row is one field of ours and one field of theirs. There are no formulas. Depending on the connector, there are up to three maps:

• What we send out: our record, as their system will read it.
• What we bring in on a sweep: their records, as we read them on a scheduled import.
• What we bring in when they call us: their records, when their system calls us.

Click Add mapping, choose Our field and Their field, then click Save field map. If their system marks a field as required and nothing is mapped to it, you are warned. You can still save, but their system may refuse the record.

Check the logs

• Delivery log: one row per event on its way to this connection, with its status (Waiting, Sending, Delivered, Failed or Dead letter), the number of attempts, the next attempt and the last error. Open a row to see each attempt.
• Call log: every call IconEngage made to the system for you: deliveries, scheduled imports and tests. Each row shows when, the endpoint, the HTTP status, the outcome (Succeeded, Failed or Refused by us), how many records moved and how long it took.

Neither log keeps the content of a request or response. They show what was called and when, never the values.

Replay a delivery

Failed deliveries are retried automatically. A Dead letter delivery has used up its retries and only moves again if someone replays it.

1. Open the connection's Delivery log.
2. Open the delivery and click Replay.
3. Click Replay delivery to confirm.

A replay adds a new attempt with the same event ID, so a receiver that already has the event can ignore the duplicate. You can replay only one delivery at a time. The connection must be enabled and not suspended.

Suspended connections

If calls keep failing, for example because the other system refuses the credentials or keeps asking IconEngage to slow down, IconEngage suspends the connection. A suspended connection makes no calls, and its deliveries wait rather than fail. It stays suspended until someone clicks Resume connection; it never resumes on a timer. Fix the cause first, then resume.

Delete a connection

On the connection, click Delete connection and confirm. Its credentials are destroyed. Its log rows stay until they age out, as they hold no values. If a delivery is in progress, disable the connection, let it finish, then delete.

Related

• Contact lookup
• Inbound webhooks and Credentials for automation flows
• Event webhooks for developers