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). If you don't change it, the default is support.
- Click "Create 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 token 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 |
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 'website_uuid=a8685f21-9916-4f16-9d45-026058d65797' \
-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.