Echo Web Contacts Integration

About

Echo's Web Contacts Integration allows you to send messages to Echo and start conversations. It also supports some additional seeker/client fields to give you more context about who the seeker is. You can use this api to start new Email and SMS conversations in Echo. For instance, you could create a "Contact Us" form on your website. When a seeker fills out that form, your server can send that form fill to Echo, and Echo will start a new email conversation with that seeker, or it will add the form fill as a new message to an existing conversation. If your form requests the seeker's phone number instead of email address, then Echo will start a text conversation with them.

Create a Web Contact Website in Echo

Before you set up the form on your website and connect that to Echo, you will need to create or choose an Echo Web Contact Website. You can find the list of Web Contact Websites for your tenant in Admin > Email > Websites.

To Create a new website:

Click "+ New Website"
Choose an Email Domain to use for email responses.
Make a note of the UUID for future use.
Change the default replying email address if desired (email address user name).
Click "New Web Contact Website".

It can be helpful to make new Echo Web Contact Websites for each new web form on your site(s). Doing so will provide you with more granular reporting.

Create a new API key in Echo

Before you continue, you will need to retrieve or generate an Echo API key. This will allow your server to send conversation messages to Echo. To create a new api token go here: Admin > Email > API Tokens and click "Generate New Token" in the top right of the page. You will be taken to a new page that shows your token. Copy this token and save it somewhere safe.

Echo will not allow you to view this token after you leave this page. You will need to use this toke later in the Authorization header we will set up.

Request parameters

Field Name	Required	Description
uuid	yes	The unique id for this record/form fill. You will use this id to retrieve this record from Echo and to distinguish it from all other form fills
website_uuid	yes	The uuid of the Echo website you want to use. You can see your list of websites here: Admin>Email>Websites
email	yes (only for email conversations)	The email address of the seeker. Echo will send outbound email messages to this email address
phone	yes (only for sms conversations)	The phone number of the seeker. Echo will send text messages to this phone number. Valid formats include: +19293685323, 929-368-5323, (929)368-5323, 9293685323, 929.368.5323, etc.
to_phone	yes ( only for sms conversations)	Must be a valid Echo provisioned phone number: Admin>Phone Numbers Must be formatted like so: +19293685323 Just copy/paste the number as shown in Echo's admin page linked above
name	no	The name of the seeker
gender	no	The gender of the seeker
age	no	The age of the seeker (0-99+)
ip_address	no	the ip address of the seeker. Use for ip geolocation lookup.
ip	no	alternative to ip_address
body	recommended	The words written by the seeker. Will be used to create a message body in Echo.
topic	no	The topic or subject of the conversation. Field is ignored if there is already an active conversation in Echo with this seeker.
outreach	no	A client metadata field.
outreach_code	no	A client metadata field.
utm_campaign	no	A utm field.
utm_source	no	A utm field.
utm_medium	no	A utm field.
utm_content	no	A utm field.
utm_outreach	no	A utm field.
url	no	The url of the webpage the seeker was on when they submitted their form. Displayed in the conversation summary.

Create a record

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {api_token}" \
 -G "https://{tenant_host}/api/webhooks/web_contacts/" \
 -d 'website_uuid=a8685f21-9916-4f16-9d45-026058d65797' \
 -d 'uuid=1234567890' \
 -d 'email=some.email.address@emailprovider.org' \
 -d 'name=The Seekers name' \
 -d 'body=The words the seeker sent to you in the form' \

View a record

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {api_token}" \
 -G "https://{tenant_host}/api/webhooks/web_contacts/<:uuid>" \
 -d 'uuid=uuidVal'

Update a record

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {api_token}" \
 -G "https://{tenant_host}/api/webhooks/web_contacts/<:uuid>" \
 -d 'website_uuid=a8685f21-9916-4f16-9d45-026058d65797' \
 -d 'uuid=1234567890' \
 -d 'email=some.email.address@emailprovider.org' \
 -d 'name=The Seekers name' \
 -d 'body=The words the seeker sent to you in the form' \

Common Issues

Not including a uuid. You have to include a uuid in your webhook. This lets Echo know that you are sending us a new message as opposed to updating an old message.
Not including a website_uuid. A list of your website uuids can be found here: Admin>Email>Websites The website uuid tells echo where to send the message and what email domain to associate a message with. It is basically Echo's concept of your gravity form. You might want to consider creating a new web contact website for each new form you create.
Spaces at the end of your bearer token or your website uuid. Sometimes when you copy/paste something, extra spaces get added on to the end. Make sure you delete any trailing whitespace.
Not including your api key or not including your api key correctly. If my api key was "abc123", then the value of the Authorization input would be "Bearer abc123" minus the double quotes.