# Delete Appointment Custom Field Source: https://docs.getmateo.com/api-reference/appointment-custom-field/delete-appointment_custom_field delete /appointment_custom_field Delete an existing appointment custom field # List Appointment Custom Fields Source: https://docs.getmateo.com/api-reference/appointment-custom-field/get-appointment_custom_field get /appointment_custom_field Retrieve a list of appointment custom fields # Update Appointment Custom Field Source: https://docs.getmateo.com/api-reference/appointment-custom-field/patch-appointment_custom_field patch /appointment_custom_field Update an existing appointment custom field # Create Appointment Custom Field Source: https://docs.getmateo.com/api-reference/appointment-custom-field/post-appointment_custom_field post /appointment_custom_field Create a new appointment custom field # Delete Appointment Details Source: https://docs.getmateo.com/api-reference/appointment-details/delete-appointment_details delete /appointment_details Delete an appointment with custom fields # List Appointment Details Source: https://docs.getmateo.com/api-reference/appointment-details/get-appointment_details get /appointment_details Retrieve a list of appointment data with custom fields # Patch appointment details Source: https://docs.getmateo.com/api-reference/appointment-details/patch-appointment_details patch /appointment_details # Post appointment details Source: https://docs.getmateo.com/api-reference/appointment-details/post-appointment_details post /appointment_details # Delete Appointment Type Source: https://docs.getmateo.com/api-reference/appointment-type/delete-appointment_type delete /appointment_type Delete an existing appointment type # List Appointment Types Source: https://docs.getmateo.com/api-reference/appointment-type/get-appointment_type get /appointment_type Retrieve a list of appointment types # Update Appointment Type Source: https://docs.getmateo.com/api-reference/appointment-type/patch-appointment_type patch /appointment_type Update an existing appointment type # Create Appointment Type Source: https://docs.getmateo.com/api-reference/appointment-type/post-appointment_type post /appointment_type Create a new appointment type # Delete appointment Source: https://docs.getmateo.com/api-reference/appointment/delete-appointment delete /appointment # List Appointments Source: https://docs.getmateo.com/api-reference/appointment/get-appointment get /appointment Retrieve a list of appointments # Patch appointment Source: https://docs.getmateo.com/api-reference/appointment/patch-appointment patch /appointment # Post appointment Source: https://docs.getmateo.com/api-reference/appointment/post-appointment post /appointment # Delete Calendar Source: https://docs.getmateo.com/api-reference/calendar/delete-calendar delete /calendar Delete an existing calendar # List Calendars Source: https://docs.getmateo.com/api-reference/calendar/get-calendar get /calendar Retrieve a list of calendars # Update Calendar Source: https://docs.getmateo.com/api-reference/calendar/patch-calendar patch /calendar Update an existing calendar # Create Calendar Source: https://docs.getmateo.com/api-reference/calendar/post-calendar post /calendar Create a new calendar # List Campaigns Source: https://docs.getmateo.com/api-reference/campaign/get-campaign get /campaign Retrieve a list of campaigns # List Channels Source: https://docs.getmateo.com/api-reference/channel/get-channel get /channel Retrieve a list of channels # List Comments Source: https://docs.getmateo.com/api-reference/comment/get-comment get /comment Retrieve a list of comments # Create Comment Source: https://docs.getmateo.com/api-reference/comment/post-comment post /comment Create a new comment # Delete Contact Custom Field Source: https://docs.getmateo.com/api-reference/contact-custom-field/delete-contact_custom_field delete /contact_custom_field Delete an existing contact custom field # List Contact Custom Fields Source: https://docs.getmateo.com/api-reference/contact-custom-field/get-contact_custom_field get /contact_custom_field Retrieve a list of contact custom fields # Update Contact Custom Field Source: https://docs.getmateo.com/api-reference/contact-custom-field/patch-contact_custom_field patch /contact_custom_field Update an existing contact custom field # Create Contact Custom Field Source: https://docs.getmateo.com/api-reference/contact-custom-field/post-contact_custom_field post /contact_custom_field Create a new contact custom field # Delete Contact Details Source: https://docs.getmateo.com/api-reference/contact-details/delete-contact_details delete /contact_details Delete a contact with marketing channels and custom fields # List Contact Details Source: https://docs.getmateo.com/api-reference/contact-details/get-contact_details get /contact_details Retrieve a list of contact data with marketing channels and custom fields # Update Contact Details Source: https://docs.getmateo.com/api-reference/contact-details/patch-contact_details patch /contact_details Update an existing contact data with marketing channels and custom fields # Create Contact Details Source: https://docs.getmateo.com/api-reference/contact-details/post-contact_details post /contact_details Create a new contact data with marketing channels and custom fields # Delete Contact List Contact Source: https://docs.getmateo.com/api-reference/contact-list-contact/delete-contact_list_contact delete /contact_list_contact Delete an existing contact list contact ### Bulk Delete This endpoint supports bulk deletion using the `in` filter on `contact_id`. You can delete up to 50 contacts from a list in a single request: ``` DELETE /contact_list_contact?contact_list_id=eq.&contact_id=in.(,,) ``` # List Contact List Contacts Source: https://docs.getmateo.com/api-reference/contact-list-contact/get-contact_list_contact get /contact_list_contact Retrieve a list of contact list contacts # Create Contact List Contact Source: https://docs.getmateo.com/api-reference/contact-list-contact/post-contact_list_contact post /contact_list_contact Create a new contact list contact # Delete Contact List Source: https://docs.getmateo.com/api-reference/contact-list/delete-contact_list delete /contact_list Delete an existing contact list # List Contact Lists Source: https://docs.getmateo.com/api-reference/contact-list/get-contact_list get /contact_list Retrieve a list of contact lists # Update Contact List Source: https://docs.getmateo.com/api-reference/contact-list/patch-contact_list patch /contact_list Update an existing contact list # Create Contact List Source: https://docs.getmateo.com/api-reference/contact-list/post-contact_list post /contact_list Create a new contact list # Clear Contact List Source: https://docs.getmateo.com/api-reference/contact-list/post-contact_list-clear post /contact_list/clear Clear all members from a contact list # Delete Contact Note Source: https://docs.getmateo.com/api-reference/contact-note/delete-contact_note delete /contact_note Delete an existing contact note # List Contact Notes Source: https://docs.getmateo.com/api-reference/contact-note/get-contact_note get /contact_note Retrieve a list of contact notes # Update Contact Note Source: https://docs.getmateo.com/api-reference/contact-note/patch-contact_note patch /contact_note Update an existing contact note # Create Contact Note Source: https://docs.getmateo.com/api-reference/contact-note/post-contact_note post /contact_note Create a new contact note # Delete Contact Source: https://docs.getmateo.com/api-reference/contact/delete-contact delete /contact Delete an existing contact # List Contacts Source: https://docs.getmateo.com/api-reference/contact/get-contact get /contact Retrieve a list of contacts # Update Contact Source: https://docs.getmateo.com/api-reference/contact/patch-contact patch /contact Update an existing contact # Create Contact Source: https://docs.getmateo.com/api-reference/contact/post-contact post /contact Create a new contact # Merge Contacts Source: https://docs.getmateo.com/api-reference/contact/post-contactmerge post /contact/merge Merge two contacts into a new one # Delete Conversation Tag Source: https://docs.getmateo.com/api-reference/conversation-tag/delete-conversation_tag delete /conversation_tag Delete an existing conversation tag # List Conversation Tags Source: https://docs.getmateo.com/api-reference/conversation-tag/get-conversation_tag get /conversation_tag Retrieve a list of conversation tags # Update Conversation Tag Source: https://docs.getmateo.com/api-reference/conversation-tag/patch-conversation_tag patch /conversation_tag Update an existing conversation tag # Create Conversation Tag Source: https://docs.getmateo.com/api-reference/conversation-tag/post-conversation_tag post /conversation_tag Create a new conversation tag # List Conversations Source: https://docs.getmateo.com/api-reference/conversation/get-conversation get /conversation Retrieve a list of conversations # Update Conversation Source: https://docs.getmateo.com/api-reference/conversation/patch-conversation patch /conversation Update an existing conversation # Create Custom Entity Definition Source: https://docs.getmateo.com/api-reference/custom-entity-definition/create-custom-entity-definition post /custom_entity_definition Create a new custom entity definition # Delete Custom Entity Definition Source: https://docs.getmateo.com/api-reference/custom-entity-definition/delete-custom-entity-definition delete /custom_entity_definition Delete an existing custom entity definition # List Custom Entity Definitions Source: https://docs.getmateo.com/api-reference/custom-entity-definition/list-custom-entity-definitions get /custom_entity_definition Retrieve a list of custom entity definitions # Update Custom Entity Definition Source: https://docs.getmateo.com/api-reference/custom-entity-definition/update-custom-entity-definition patch /custom_entity_definition Update an existing custom entity definition # Create Custom Entity Source: https://docs.getmateo.com/api-reference/custom-entity/create-custom-entity post /custom_entity Create a new custom entity # Delete Custom Entity Source: https://docs.getmateo.com/api-reference/custom-entity/delete-custom-entity delete /custom_entity Delete an existing custom entity # List Custom Entitys Source: https://docs.getmateo.com/api-reference/custom-entity/list-custom-entitys get /custom_entity Retrieve a list of custom entitys # Update Custom Entity Source: https://docs.getmateo.com/api-reference/custom-entity/update-custom-entity patch /custom_entity Update an existing custom entity # Delete Custom Field Source: https://docs.getmateo.com/api-reference/custom-field/delete-custom_field delete /custom_field Delete an existing custom field # List Custom Fields Source: https://docs.getmateo.com/api-reference/custom-field/get-custom_field get /custom_field Retrieve a list of custom fields # Update Custom Field Source: https://docs.getmateo.com/api-reference/custom-field/patch-custom_field patch /custom_field Update an existing custom field # Create Custom Field Source: https://docs.getmateo.com/api-reference/custom-field/post-custom_field post /custom_field Create a new custom field # Delete Deal Custom Field Source: https://docs.getmateo.com/api-reference/deal-custom-field/delete-deal_custom_field delete /deal_custom_field Delete an existing deal custom field # List Deal Custom Fields Source: https://docs.getmateo.com/api-reference/deal-custom-field/get-deal_custom_field get /deal_custom_field Retrieve a list of deal custom fields # Update Deal Custom Field Source: https://docs.getmateo.com/api-reference/deal-custom-field/patch-deal_custom_field patch /deal_custom_field Update an existing deal custom field # Create Deal Custom Field Source: https://docs.getmateo.com/api-reference/deal-custom-field/post-deal_custom_field post /deal_custom_field Create a new deal custom field # Delete Deal Details Source: https://docs.getmateo.com/api-reference/deal-details/delete-deal_details delete /deal_details Delete a deal with custom fields # List Deal Details Source: https://docs.getmateo.com/api-reference/deal-details/get-deal_details get /deal_details Retrieve a list of deal data with custom fields # Update Deal Details Source: https://docs.getmateo.com/api-reference/deal-details/patch-deal_details patch /deal_details Update an existing deal data with custom fields # Create Deal Details Source: https://docs.getmateo.com/api-reference/deal-details/post-deal_details post /deal_details Create a new deal data with custom fields # Delete Deal Source: https://docs.getmateo.com/api-reference/deal/delete-deal delete /deal Delete an existing deal # List Deals Source: https://docs.getmateo.com/api-reference/deal/get-deal get /deal Retrieve a list of deals # Update Deal Source: https://docs.getmateo.com/api-reference/deal/patch-deal patch /deal Update an existing deal # Create Deal Source: https://docs.getmateo.com/api-reference/deal/post-deal post /deal Create a new deal # List Employees Source: https://docs.getmateo.com/api-reference/employee/get-employee get /employee Retrieve a list of employees # Update Employee Source: https://docs.getmateo.com/api-reference/employee/patch-employee patch /employee Update an existing employee # Create Employee Source: https://docs.getmateo.com/api-reference/employee/post-employee post /employee Create a new employee # List Events Source: https://docs.getmateo.com/api-reference/event/get-event get /event Retrieve a list of events # Format Phone Numbers Source: https://docs.getmateo.com/api-reference/format/format-phone-number post /format Format phone numbers to E.164 format with specified country codes # Generate Content Source: https://docs.getmateo.com/api-reference/generate-content/generate-content post /generate_content Parse any HTML or text into our multi-channel messaging schema # List Imports Source: https://docs.getmateo.com/api-reference/import/get-import get /import Retrieve a list of imports # Create Import Source: https://docs.getmateo.com/api-reference/import/post-import post /import Create a new import The `payload` is an array of objects, where each object will be imported. For all three types, we expect the same payload you would also send to their respective `/x_details` endpoint. To simplify integrations, deals and appointments both accept an additional `contact_external_id` that can be set instead of the `contact_id`. For cross-contact updates by external ID, set `allow_deal_reassignment` for deals or `allow_appointment_reassignment` for appointments. ### Parsing Phone Numbers For `contact_details` imports, we also accept a list of phone numbers for both `whatsapp` and `sms`: ```json theme={null} { "whatsapp": ["+493813901", "+18494383"], "sms": ["+493813901", "+18494383"] } ``` We will parse each option and use the first valid phone number out of the list as the input. To improve accuracy, you can pass a `country_codes` array along: ```json theme={null} { "whatsapp": ["+493813901", "+18494383"], "sms": ["+493813901", "+18494383"], "country_codes": ["DE", "AT"] } ``` This means you do not have to call the `/format` endpoint separately. It will be handled within the import. # Get journey execution Source: https://docs.getmateo.com/api-reference/journey-execution/get-journey_execution get /journey_execution # Start a journey execution Source: https://docs.getmateo.com/api-reference/journey-execution/post-journey_execution post /journey_execution Trigger a journey execution for a contact via HTTP webhook # Start batch journey executions Source: https://docs.getmateo.com/api-reference/journey-execution/post-journey_execution-batch post /journey_execution/batch Queue multiple journey executions for a single journey. Each contact is processed independently. # List Journey Nodes Source: https://docs.getmateo.com/api-reference/journey-node/get-journey_node get /journey_node Retrieve a list of journey nodes # List Journey Versions Source: https://docs.getmateo.com/api-reference/journey-version/get-journey_version get /journey_version Retrieve a list of journey versions # List Journeys Source: https://docs.getmateo.com/api-reference/journey/get-journey get /journey Retrieve a list of journeys # Delete Location Source: https://docs.getmateo.com/api-reference/location/delete-location delete /location Delete an existing location # List Locations Source: https://docs.getmateo.com/api-reference/location/get-location get /location Retrieve a list of locations # Update Location Source: https://docs.getmateo.com/api-reference/location/patch-location patch /location Update an existing location # Create Location Source: https://docs.getmateo.com/api-reference/location/post-location post /location Create a new location # List Marketing Channels Source: https://docs.getmateo.com/api-reference/marketing-channel/get-marketing_channel get /marketing_channel Retrieve a list of marketing channels # Delete Marketing Subscription Source: https://docs.getmateo.com/api-reference/marketing-subscription/delete-marketing_subscription delete /marketing_subscription Delete an existing marketing subscription # List Marketing Subscriptions Source: https://docs.getmateo.com/api-reference/marketing-subscription/get-marketing_subscription get /marketing_subscription Retrieve a list of marketing subscriptions # Update Marketing Subscription Source: https://docs.getmateo.com/api-reference/marketing-subscription/patch-marketing_subscription patch /marketing_subscription Update an existing marketing subscription # Create Marketing Subscription Source: https://docs.getmateo.com/api-reference/marketing-subscription/post-marketing_subscription post /marketing_subscription Create a new marketing subscription # List Message Actions Source: https://docs.getmateo.com/api-reference/message-action/get-message_action get /message_action Retrieve a list of message actions # Delete Message Source: https://docs.getmateo.com/api-reference/message/delete-message delete /message Delete an existing message # List Messages Source: https://docs.getmateo.com/api-reference/message/get-message get /message Retrieve a list of messages # List Provider Template Approvals Source: https://docs.getmateo.com/api-reference/provider-template-approval/get-provider_template_approval get /provider_template_approval Retrieve a list of provider template approvals # List Providers Source: https://docs.getmateo.com/api-reference/provider/get-provider get /provider Retrieve a list of providers # List Recipients Source: https://docs.getmateo.com/api-reference/recipient/get-recipient get /recipient Retrieve a list of recipients # Send Broadcast Message Source: https://docs.getmateo.com/api-reference/send-broadcast/send-a-broadcast-message post /send_broadcast Send a Broadcast message to a list of recipients and / or segments # Send Message Source: https://docs.getmateo.com/api-reference/send-message/send-a-message post /send_message Send a message ### Postal Messages When sending a postal message, the recipient must contain the `contact_id` and no `handle`. If the contact does not exist yet, make sure to create it first. # Create Signed Url Source: https://docs.getmateo.com/api-reference/storage/create-a-signed-url post /storage/sign/{bucketName}/* Create a signed url for an object in a bucket. You can use this url to download the object # Delete Template Source: https://docs.getmateo.com/api-reference/template/delete-template delete /template Delete an existing template # List Templates Source: https://docs.getmateo.com/api-reference/template/get-template get /template Retrieve a list of templates # Receive Webhook from SAP Emarsys Source: https://docs.getmateo.com/api-reference/webhook-receivers/post-sapemarsys-send-message post /webhook_receivers/sapemarsys/send_message Receive a webhook from SAP Emarsys to send a message Requires the SAP Emarsys entitlement. The endpoint also accepts any contact field with the `contact_` prefix, for example `contact_full_name`, `contact_birthday`, etc. # Delete Webhook Source: https://docs.getmateo.com/api-reference/webhook/delete-webhook delete /webhook Delete an existing webhook # List Webhooks Source: https://docs.getmateo.com/api-reference/webhook/get-webhook get /webhook Retrieve a list of webhooks # Update Webhook Source: https://docs.getmateo.com/api-reference/webhook/patch-webhook patch /webhook Update an existing webhook # Create Webhook Source: https://docs.getmateo.com/api-reference/webhook/post-webhook post /webhook Create a new webhook # Delete Data Source: https://docs.getmateo.com/concepts/delete Using the DELETE method, you can remove rows. To delete rows in a table, use the `DELETE` verb plus Horizontal Filtering on the primary keys(s). For instance deleting a contact: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?id=eq.123" \ -X DELETE ``` ```bash theme={null} HTTP/1.1 204 No Content ``` No response body will be returned by default but you can add a `select` query parameter to select the columns that should be returned: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?id=1234&select=id,full_name" \ -X DELETE -H "Content-Type: application/json" ``` ```bash theme={null} HTTP/1.1 200 OK ``` ```json theme={null} { "id": 1234, "full_name": "Max Mustermann" } ``` # Insert Data Source: https://docs.getmateo.com/concepts/insert You can insert new data using the POST method To create a row post a JSON object whose keys are the names of the columns you would like to create. Missing properties will be set to default values when applicable. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact" \ -X POST -H "Content-Type: application/json" \ -d '{ "full_name": "Max Mustermann" }' ``` ```bash theme={null} HTTP/1.1 201 Created ``` No response body will be returned by default but you can add a `select` query parameter to select the columns that should be returned: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?select=full_name,birthday" \ -X POST -H "Content-Type: application/json" \ -d '{ "full_name": "Max Mustermann" }' ``` ```bash theme={null} HTTP/1.1 201 Created ``` ```json theme={null} { "full_name": "Max Mustermann", "birthday": null } ``` # Pagination Source: https://docs.getmateo.com/concepts/pagination Learn how to paginate through large data sets. Pagination controls the number of rows returned for an API resource response. One way to request limits and offsets is by using query parameters. For example: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?limit=15&offset=30" ``` You can use headers to specify the range of rows desired. This request gets the first twenty contacts: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact" -i \ -H "Range-Unit: items" \ -H "Range: 0-19" ``` Note that the api may respond with fewer if unable to meet your request. There is a hard limit of 50 rows per request. If you set the limit to more than 50, the API will still return max 50 rows. # Read Data Source: https://docs.getmateo.com/concepts/read Using the GET method, you can retrieve rows. ## Horizontal Filtering You can filter result rows by adding conditions on columns. For instance, to lookup contacts that did not receive any campaign messages this month: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?campaign_messages_this_month=eq.0" ``` You can evaluate multiple conditions on columns by adding more query string parameters. For instance, to return contacts that did not receive any campaign messages this month and opted in for WhatsApp marketing: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?campaign_messages_this_month=eq.0&whatsapp_marketing_opt_in=eq.true" ``` ### Operators These operators are available: | Abbreviation | Meaning | | - | - | | eq | equals | | gt | greater than | | gte | greater than or equal | | lt | less than | | lte | less than or equal | | neq | not equal | | like | LIKE operator (to avoid [URL encoding](https://en.wikipedia.org/wiki/Percent-encoding) you can use `*` as an alias of the percent sign `%` for the pattern) | | ilike | ILIKE operator (to avoid [URL encoding](https://en.wikipedia.org/wiki/Percent-encoding) you can use `*` as an alias of the percent sign `%` for the pattern) | | in | one of a list of values, e.g. `?a=in.(1,2,3)` -- also supports commas in quoted strings like `?a=in.("hi,there","yes,you")` | | is | checking for exact equality (null,true,false,unknown) | | isdistinct | not equal, treating `NULL` as a comparable value | | cs | contains e.g. `?tags=cs.{example, new}` | | cd | contained in e.g. `?values=cd.{1,2,3}` | | not | negates another operator, see [Logical Operators](#logical-operators) | | or | logical `OR`, see [Logical Operators](#logical-operators) | | and | logical `AND`, see [Logical Operators](#logical-operators) | ### Logical Operators Multiple conditions on columns are evaluated using `AND` by default, but you can combine them using `OR` with the `or` operator. For example, to return contacts with either a SMS or a WhatsApp marketing opt in: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?or=(whatsapp_marketing_opt_in.eq.true,email_marketing_opt_in.eq.true)" ``` To negate any operator, you can prefix it with `not` like `?a=not.eq.2` or `?not.and=(a.gte.0,a.lte.100)`. ## Vertical Filtering To be more effiecient, it is always wise to retrieve only the columns you need. You can do this by specifying the columns in the `select` query string parameter. For example, to retrieve only the `id` and `name` columns: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?select=id,name" ``` ## Ordering The reserved word `order` reorders the response rows. It uses a comma-separated list of columns and directions: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?order=full_name.desc,email.asc" ``` If no direction is specified it defaults to ascending order: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?order=full_name" ``` If you care where nulls are sorted, add `nullsfirst` or `nullslast`: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?order=full_name.nullsfirst" ``` ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?order=full_name.nullslast" ``` # Resource Embedding Source: https://docs.getmateo.com/concepts/resource-embedding Our API supports including related resources in a single API call. This reduces the need for many API requests. This is an advanced feature. Only start using it if you are comfortable with our API. ## Many-to-One Relationships Since a `message` always has a `conversation`, they have a many-to-one relationship. This enables us to request all the messages and the conversation for each message. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/message?select=id,conversation(subject)" ``` ```json theme={null} [ { "id": 1, "conversation": { "subject": "Hello" } }, { "id": 2, "conversation": { "subject": "Goodbye" } } ] ``` Note that the embedded `conversation` is returned as a JSON object because of the “to-one” end. ## One-to-Many Relationships The foreign key reference establishes the inverse one-to-many relationship. In this case, message returns as a JSON array because of the “to-many” end. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/conversation?select=id,subject,messages(id)" ``` ```json theme={null} [ { "id": 1, "subject": "Hello", "messages": [ { "id": 1 }, { "id": 2 } ] }, { "id": 2, "subject": "Goodbye", "messages": [ { "id": 3 } ] } ] ``` ## Many-to-Many Relationships In this example, a `conversation` has `tag`s assigned via a `conversation_tag` relation. This is a many-to-many relationship. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/conversation?select=id,subject,tag(name)" ``` ```json theme={null} [ { "id": 1, "subject": "Hello", "tag": [ { "name": "greeting" }, { "name": "important" } ] }, { "id": 2, "subject": "Goodbye", "tag": [ { "name": "farewell" } ] } ] ``` # Update Data Source: https://docs.getmateo.com/concepts/update Using the PATCH method, you can update rows. To update a row or rows in a table, use the PATCH verb. Use Horizontal Filtering to specify which record(s) to update. Here is an example query activating a webhook. ```bash theme={null} curl "https://api.getmateo.com/api/v1/webhook?id=1234" \ -X PATCH -H "Content-Type: application/json" \ -d '{ "active": true }' ``` ```bash theme={null} HTTP/1.1 204 No Content ``` No response body will be returned by default but you can add a `select` query parameter to select the columns that should be returned: ```bash theme={null} curl "https://api.getmateo.com/api/v1/webhook?id=1234&select=id,name,active" \ -X PATCH -H "Content-Type: application/json" \ -d '{ "active": true }' ``` ```bash theme={null} HTTP/1.1 200 OK ``` ```json theme={null} { "id": 1234, "name": "My Webhook", "active": true } ``` # Upsert Data Source: https://docs.getmateo.com/concepts/upsert Using either POST or PUT, you can upsert rows. You can upsert data with `POST` and the `Prefer: resolution=merge-duplicates` header: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact" \ -X POST -H "Content-Type: application/json" \ -H "Prefer: resolution=merge-duplicates" \ -d '{ "id": 1, full_name": "Max Mustermann" }' ``` By default, upsert operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with `Prefer: resolution=ignore-duplicates`. ### On Conflict By specifying the on\_conflict query parameter, you can make upsert work on a column(s) that has a UNIQUE constraint. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?on_conflict=external_id" \ -X POST -H "Content-Type: application/json" \ -H "Prefer: resolution=merge-duplicates" \ -d '{ "external_id": 1, full_name": "Max Mustermann" }' ``` ### PUT You can also upsert data with `PUT`: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?id=eq.123" \ -X PUT -H "Content-Type: application/json" \ -d '{ "id": 123, "full_name": "Max Mustermann" }' ``` All the columns must be specified in the request body, including the primary key column(s). ### Response If the data was inserted, the response status code will be `201 Created`. If the data was updated, the response status code will be `200 OK`. The response body will be empty by default, but you can add a `select` query parameter to select the columns that should be returned: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?id=eq.123&select=id,full_name" \ -X PUT -H "Content-Type: application/json" \ -d '{ "id": 123, "full_name": "Max Mustermann" }' ``` ```json theme={null} { "id": 1234, "full_name": "Max Mustermann" } ``` # Introduction Source: https://docs.getmateo.com/introduction Understand general concepts, response codes, and authentication strategies. **This legacy API is deprecated and will be phased out.** Follow the [legacy API migration guide](https://developers.getmateo.com/docs/resources/legacy-api-migration-guide) to move to the new public API. ## Base URL The hellomateo API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP. All requests contain the following base URL: ``` https://integration.getmateo.com/api/v1 ``` ## Authentication To authenticate you need to add an Authorization header with the contents of the header being Bearer 123456789 where 123456789 is your API Key. ``` Authorization: Bearer 123456789 ``` ## Response Codes Mateo uses standard HTTP codes to indicate the success or failure of your requests. In general, `2xx` HTTP codes correspond to success, `4xx` codes are for user-related failures, and `5xx` codes are for infrastructure issues. | Status | Description | | - | - | | 200 | Successful request. | | 400 | Check that the parameters were correct. | | 401 | The API key used was missing. | | 403 | The API key used was invalid. | | 404 | The resource was not found. | | 429 | The rate limit was exceeded. | | 5xx | Indicates an error with hellomateo servers. | ### Error Response All error responses are of type `application/json` and return a body with the following structure: ```json theme={null} { "code": "API_ERROR_CODE", "message": "A human-readable message explaining the error.", "hint": "A human-readable message explaining how to fix the error.", "status": 400 } ``` # Limits Source: https://docs.getmateo.com/limits To ensure reliabilty and performance, we have certain limits in place. Learn more about them here. Limits may change in the future to balance for demand and reliabilty. Try to optimise your requests. ## Request Timeout We have a global request timeout of **two seconds**. If a request takes longer than two seconds to execute, it will be terminated and you will receive an error response. This is to ensure that the database is not overloaded and that the API remains responsive. If you hit that limit, try to optimise your query to make it faster. You can consult [Recipes](./recipes) for implementation guidance on common use cases, or contact the helomateo for support. ## Rate Limits To ensure the reliability and performance of the API, we have rate limits in place. These limits are designed to prevent abuse and ensure that the API remains responsive for all users. There are two types of rate limits: * **requests-per-second**: The number of requests you can make in a second is limited to 10 tokens. Different request types consume different amounts of tokens: * `GET` requests: 1 token * `send_message` and `send_broadcast`: 3 tokens each * All other requests (`POST`, `PUT`, `PATCH`, `DELETE`): 2 tokens each * **requests-per-day**: The number of requests you can make in a day is limited to 10000. If you hit any of these limits, you will receive a `429` response error code. To prevent this, we recommend reducing the rate at which you request the API. This can be done by introducing a queue mechanism or reducing the number of concurrent requests per second. All limits can be increased for trusted senders by request. If you have specific requirements, contact support to request a rate increase. ### Response Headers The response headers describe your current rate limit following every request in conformance with the [IETF standard](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers): | Header Name | Description | | - | - | | `ratelimit-type` | Type of the ratelimit (see above, e.g. `requests-per-second`) | | `ratelimit-limit` | Maximum number of requests allowed within a window. | | `ratelimit-remaining` | How many requests you have left within the current window. | | `ratelimit-reset` | How many seconds until the limits are reset. | | `retry-after` | How many seconds you should wait before making a follow-up request. | # Contact Import Source: https://docs.getmateo.com/recipes/contact-import Learn how to efficiently import contacts into Hellomateo. Let us assume you have 50.000 contacts in your ERP system, and you want to import them into Hellomateo. You can do this either via the CSV upload within the Hellomateo Web App, or via the API. This guide will show you how to import contacts using the API. To not hit rate-limits, we we recommend using the [Import API](/api-reference/import/post-import) to import contacts in batches. An import is a simple entity that is defined by a `type` and a `payload`. The `type` defines what data you are importing, and the `payload` is the actual data you are importing. To import contact data including custom fields and marketing subscriptions, you can use the following payload: ```json theme={null} { "type": "contact_details", "payload": [ { "external_id": "1", "email": "my@contact.com", "my_custom_field_key": "my_custom_field_value", "my_marketing_channel_key": "accepted" }, { "external_id": "2", "email": "another@contact.com", "my_custom_field_key": "another_custom_field_value", "my_marketing_channel_key": "declined" } ] } ``` If you are integrating with an external ERP or CRM system, you can use the `external_id` to store the ID of the contact from the external system directly within Hellomateo. This way, you do not need to keep track of the Hellomateo `id`. Note that the `external_id`, and all handles (`whatsapp`, `email`, `sms`, etc) are unique identifiers for the contact. If you import a contact with the same value multiple times, the contact will be updated with the new data. ## Working with Datetime Data When importing contacts with datetime fields, always send datetime values in **ISO 8601 format with timezone information** to ensure data accuracy. ### Required Format Use the format: `YYYY-MM-DDTHH:mm:ss±HH:mm` or `YYYY-MM-DDTHH:mm:ssZ` **Examples:** ```json theme={null} { "type": "contact_details", "payload": [ { "external_id": "1", "email": "my@contact.com", "birthday": "1990-05-15T00:00:00Z", "last_contacted_at": "2024-03-15T14:30:00+01:00" } ] } ``` ### Default Timezone If no timezone is provided, **the system defaults to UTC**. However, always include timezone information explicitly to avoid ambiguity and potential data errors. **Avoid:** ``` "last_contacted_at": "2024-03-15T14:30:00" // ambiguous - will be interpreted as UTC ``` **Prefer:** ``` "last_contacted_at": "2024-03-15T14:30:00Z" // explicit UTC ``` The request then imports a job that is processed **in the background**. We do not give any guarantee on the processing time, but you can check the status of the import job by calling the [Get Import API](/api-reference/get-import) with the `id` of the import job that was returned in the response of the `Post Import API`. Make sure to `select` the `id` of the import job when you create the import job. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/import?select=id" \ -X POST -H "Content-Type: application/json" \ -d '[ ... the payload ... ]' ``` ```bash theme={null} HTTP/1.1 201 Created ``` ```json theme={null} { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" } ``` When the import is completed, you will find its result in the response of the [Get Import API](/api-reference/get-import). ```json theme={null} { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "total_count": 10, "success_count": 9, "failed_count": 1, "failed": [ { "code": "23514", "message": "duplicate key value violates unique constraint \"unique_email\"", "input": { "external_id": "2", "email": "another@contact.com", "my_custom_field_key": "another_custom_field_value", "my_marketing_channel_key": "declined" } } ] } ``` In this example, 10 contacts were imported, 9 were successful, and 1 failed due to a duplicate email address. The failed contacts are returned in the `failed` array with the reason why they failed. There is a limit to the number of contacts you can import on a single day. Consult the [Limits](/limits) page for more information. If you need to import more contacts, please contact our support team. # Contact Sync Source: https://docs.getmateo.com/recipes/contact-sync Learn how to setup a (bi-directional) contact sync between Hellomateo and an external system. Lets assume you have just imported 50.000 contacts into hellomateo using the [Contact Import](/recipes/contact-import) recipe. You sent out your first campaigns and collected a lot of Marketing Opt-Ins - great! But you need these opt-ins to be reflected in your ERP or CRM system as well. This is where the Contact Sync comes into play. In essence, there are two ways to sync contacts between Hellomateo and an external system: 1. **Push Sync**: Hellomateo pushes contact updates to the external system via a webhook. 2. **Pull Sync**: The external system pulls contact updates from Hellomateo via the API. We recommend using the Push Sync, as it is more efficient and real-time. However, if you are not able to set up a webhook on your external system, you can use the Pull Sync. To set up a Push Sync, you need to create a webhook in Hellomateo that sends contact updates to your external system. Learn how to set up and consume webhooks in the [Setting up Webhooks](/webhooks/setting-up-webhooks) guide. Upon receiving a webhook, you can use the `external_id` of the contact that is also part of the webhook payload to find and update the contact in your system. If the contact does not exist yet within the external system, the `external_id` will be `null` and you can create it instead. Make sure to [update the contact](/api-reference/contact/patch-contact) in Hellomateo with the `external_id` of the contact in your system after it has been created. The Pull Sync is a bit more complex, as you need to periodically poll the Hellomateo API for changes. We recommend setting up a cron job that runs at least every night to fetch all contacts, marketing subscriptions, and custom fields from Hellomateo that were updated since the last run. You can then update the contacts in your system accordingly. For example, you can use the [Get Contact Custom Field API](/api-reference/contact-custom-field/get-contact_custom_field) to retrieve all values that have been updated since a certain timestamp for a specific custom field: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key" ``` If you are interested in just a single contact, you can filter on the `contact_id`: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value&contact_id=eq.1&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key" ``` If you just know the `external_id` of the contact, you can use [Resource Embeddings](/concepts/resource-embedding) to filter on the `external_id` of the contact: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value,contact!inner(external_id)&contact.external_id=eq.1&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key" ``` You can leverage all of the available [filtering options](/concepts/read) to only retrieve the data you need. Similarly, you can query marketing subscriptions and contacts using the [Get Contact API](/api-reference/contact/get-contact) and the [Get Marketing Subscription API](/api-reference/marketing-subscription/get-marketing_subscription). For example, to get all whatsapp marketing subscriptions that have been updated: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/marketing_subscription?select=key,value&updated_at=gte.2021-01-01T00:00:00Z&channel=eq.whatsapp" ``` Use [pagination](/concepts/pagination) to retrieve the data in chunks. If you have a lot of contacts that are updated frequently, you might hit our rate limits. In this case, migrate to the Push Sync. # Custom Entity Journeys Source: https://docs.getmateo.com/recipes/custom-entity-journeys Learn how to use custom entities to sync external data and trigger journey automations. Custom entities are schema-driven data objects attached to contacts. They allow you to sync structured data from external systems (e.g. vouchers, tickets, subscriptions) into Hellomateo and automatically trigger journeys when that data is created or updated. ## Prerequisites Before you can trigger journeys with custom entities, you need to: 1. Create a journey in Hellomateo with a **Custom Entity** trigger node 2. Set the trigger's `event_type` to `custom_entity_created` or `custom_entity_changed` 3. Set the `custom_entity_definition_id` on the trigger node to scope it to a specific entity type 4. Publish the journey and set it to active ## Create a Custom Entity Definition A custom entity definition describes the shape of your data. Create one via the API: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/custom_entity_definition" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Prefer: return=representation" \ -d '{ "key": "voucher", "name": "Voucher", "schema": { "type": "object", "properties": { "voucher_id": { "type": "string" }, "status": { "type": "string" }, "code": { "type": "number" } }, "required": ["voucher_id", "status"] } }' ``` The `key` is a unique, human-readable identifier for the definition. The `schema` field accepts a JSON Schema that validates entity data on write. ## Create a Custom Entity Creating a custom entity triggers any journey with a `custom_entity_created` trigger scoped to the matching definition: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/custom_entity" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Prefer: return=representation" \ -d '{ "custom_entity_definition_key": "voucher", "contact_id": "CONTACT_UUID", "external_id": "VOUCH-12345", "data": { "voucher_id": "VOUCH-12345", "status": "sent", "code": 102938405 } }' ``` | Field | Type | Required | Description | | - | - | - | - | | `custom_entity_definition_key` | string | Yes\* | Key of the definition. Alternative to `custom_entity_definition_id` | | `custom_entity_definition_id` | UUID | Yes\* | ID of the definition. Alternative to `custom_entity_definition_key` | | `contact_id` | UUID | Yes | The contact this entity belongs to | | `external_id` | string | No | Your external system's ID for this entity (enables upsert behavior) | | `data` | object | Yes | The entity payload, validated against the definition's schema | \*Provide either `custom_entity_definition_key` or `custom_entity_definition_id`. ## Update a Custom Entity Updating a custom entity's `data` field triggers any journey with a `custom_entity_changed` trigger scoped to the matching definition. The journey is only triggered when the `data` field actually changes: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/custom_entity?external_id=eq.VOUCH-12345&custom_entity_definition_key=eq.voucher" \ -X PATCH \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Prefer: return=representation" \ -d '{ "data": { "voucher_id": "VOUCH-12345", "status": "used", "code": 120939485932 } }' ``` ## Discovering Custom Entity Journeys You can query the API to find journeys that have custom entity triggers: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/journey?select=id,name,status,latest_published_version:latest_published_version_id(id,version,journey_node!inner(id,event_type,custom_entity_definition_id))&latest_published_version.journey_node.event_type=in.(custom_entity_created,custom_entity_changed)" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` This returns all journeys with custom entity triggers, including their `custom_entity_definition_id` so you know which entity types they respond to. ## Examples ### Voucher Campaigns Sync voucher codes from your marketing platform. Use `custom_entity_created` to send the voucher to the contact, and `custom_entity_changed` to trigger a follow-up when the voucher is redeemed. ### ERP Sync Sync contract or invoice data from your ERP. Trigger a journey when a new contract is created to kick off an onboarding flow. ### Form Submissions Store structured form submission data as custom entities. Use `custom_entity_created` to trigger a follow-up journey that sends a confirmation and assigns the contact to a sales rep. ## Best Practices * **Use `external_id` for idempotency**: Set `external_id` to your system's unique identifier (e.g. voucher code) so you can update entities by filtering on it * **Prefer `custom_entity_definition_key` over UUID**: Keys are human-readable and stable across environments * **Keep schemas simple**: Only include fields you need in the journey. Complex nested schemas are supported but harder to work with in the expression editor * **One definition per domain object**: Create separate definitions for orders, tickets, subscriptions, etc. rather than a generic one * **Test with `custom_entity_created` first**: It's easier to verify since it fires on every insert, while `custom_entity_changed` only fires when `data` actually changes # Embed Inbox Source: https://docs.getmateo.com/recipes/embed-inbox Learn how to embed your customer chats directly into your own systems like ERP, CRM, or internal dashboard. With the **hellomateo Embed**, you can integrate your customer chats directly into your own systems — for example, your **ERP**, **CRM**, or **internal dashboard**. This makes communication faster, easier, and keeps your team in one workspace. ## 🧭 Two ways to show your inbox You can embed either **a single conversation** or **your entire inbox**. ### Option 1: Single conversation Show only one customer chat — perfect for displaying the chat directly in your ERP next to a contact. 👉 **URL format:** ``` https://app.getmateo.com/embed/conversations//single ``` ### Option 2: Full inbox Display all your conversations in one view. 👉 **URL:** ``` https://app.getmateo.com/embed/conversations ``` To make it work, simply **add your employee access token** at the end of the URL: ``` ?access_token= ``` ✅ **Examples:** **Single conversation:** ``` https://app.getmateo.com/embed/conversations/12345/single?access_token=abcd1234 ``` **Full inbox:** ``` https://app.getmateo.com/embed/conversations?access_token=abcd1234 ``` ## 🧩 How to get the conversation for a contact If you want to show the chat for a specific customer, you'll need their **conversation ID**. Here's how to find it via the API (for example, using the `external_id`): ### 1️⃣ Get the conversation by external ID ```bash theme={null} curl --request GET --url "https://integration.getmateo.com/api/v1/contact?external_id=eq.&select=conversation(id)" --header "Authorization: Bearer " ``` You'll receive a `conversation.id` in the response — use it in your embed link. ## 🔑 Create an Employee Token If you don't have an employee token yet, you can create one in your hellomateo account: 1. Go to **Settings → Integrations → Employee Tokens** 2. Click **Create Employee Token** 3. Enter a **token name**, select the **employee**, and click **Create Token** 4. Copy and save the token — it will **only be shown once** ## 📧 Pre-filling Conversations via URL You can now create links that automatically pre-fill conversation recipients. Users will review and confirm before sending. ### URL Format ``` https://[your-domain]/conversations/new?channel_id=[CHANNEL_ID]&handle=[RECIPIENT1,RECIPIENT2,...] ``` ### Required Parameters * `channel_id`: The UUID of your channel (get this from your channel settings) * `handle`: Comma-separated recipient handles (phone, email, etc.) ### ⚠️ Important: URL Encoding **Special characters MUST be encoded:** | Character | Encoded As | | - | - | | `+` (plus) | `%2B` | | Space | `%20` | | `@` (at) | `%40` | | `,` (comma) | `%2C` (optional, but recommended) | Please note that if you don't want to encode it manually (recommended), then enter the handles normally with the symbols and let the AI encode ONLY THE PARAMATERS and not the whole url ## Working Examples ### Single Recipient - Phone with `+` (Encoded) ``` https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678 ``` ### Single Recipient - Phone without `+` ``` https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=4915212345678 ``` ### Single Recipient - Email (Encoded) ``` https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=kunde%40beispiel.de ``` ### Single Recipient - Handle with Spaces (Encoded) ``` https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=my%20custom%20handle ``` ### Multiple Recipients - Broadcast Mode (2 recipients) ``` https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,%2B4917612398765 ``` ### Multiple Recipients - Broadcast Mode (3 recipients) ``` https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,%2B4917612398765,%2B4916023456789 ``` ### Multiple Recipients - Mixed Formats ``` https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,4917612398765,004916023456789 ``` ### Multiple Recipients - Emails (5 recipients) ``` https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=kunde1%40beispiel.de,kunde2%40beispiel.de,support%40firma.com,info%40test.de,kontakt%40company.de ``` ### Multiple Recipients - With Spaces (Encoded) ``` https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=user%20one,user%20two,user%20three ``` ## ❌ Common Mistakes **Don't use unencoded special characters:** ``` ❌ handle=+4915212345678,+4917612398765 (+ will be lost) ❌ handle=kunde@beispiel.de (may break the URL) ❌ handle=my custom handle (spaces will break the URL) ``` **Always encode:** ``` ✅ handle=%2B4915212345678,%2B4917612398765 ✅ handle=kunde%40beispiel.de ✅ handle=my%20custom%20handle ``` # Introduction Source: https://docs.getmateo.com/recipes/introduction A collection of recipes for common use cases. Missing anything? Let us know and we will add a recipe for your use case! Learn how to efficiently import contacts into Hellomateo. Learn how to setup a (bi-directional) contact sync between Hellomateo and an external system. Learn how to retrieve a log of messages sent and received within Hellomateo. Learn how to send attachments. Learn how to trigger journey executions via HTTP API endpoint. Learn how to embed your customer chats directly into your own systems like ERP, CRM, or internal dashboard. Learn how to use custom entities to sync external data and trigger journey automations. # Message Log Source: https://docs.getmateo.com/recipes/message-log Learn how to retrieve a log of messages sent and received within Hellomateo. Lets assume you have a ERP system and need to sync back a message log for every contact across channels from Hellomateo. In essence, there are two ways to sync back messages to the external system: 1. **Push Sync**: Hellomateo pushes messages to the external system via a webhook. 2. **Pull Sync**: The external system pulls messages from Hellomateo via the API. We recommend using the Push Sync, as it is more efficient and real-time. However, if you are not able to set up a webhook on your external system, you can use the Pull Sync. To set up a Push Sync, you need to create a webhook in Hellomateo that sends contact updates to your external system. Learn how to set up and consume webhooks in the [Setting up Webhooks](/webhooks/setting-up-webhooks) guide. Upon receiving a webhook, you can either use the `contact_id` of the conversation directly from the webhook payload, or query `external_id` of the contact: ```bash theme={null} curl "https://integration.getmateo.com/api/v1/contact?select=external_id&contact_id=eq." ``` The webhook payload also contains the `raw_content` of the message, which is either the raw text or for emails the HTML content. You can use this to update the message log in your system. The Pull Sync is a bit more complex, as you need to periodically poll the Hellomateo API for changes. We recommend setting up a cron job that runs at least every night to fetch all messages that were updated since the last run. ```bash theme={null} curl "https://integration.getmateo.com/api/v1/message?select=id,raw_content,timestamp&contact_id=eq.1×tamp=gte.2021-01-01T00:00:00Z&limit=10&offset=0" ``` You can leverage all of the available [filtering options](/concepts/read) to only retrieve the data you need, and [pagination](/concepts/pagination) to retrieve the data in chunks. If you have a lot of messages per period, you might hit our rate limits. In this case, migrate to the Push Sync. # Sending Attachments Source: https://docs.getmateo.com/recipes/sending-attachments Learn how to send attachments All messaging endpoints support sending attachments. You can include either one or multiple attachments in one of two formats: 1. **HTTPS URL**: We'll download the attachment from the provided URL. This is the easiest method, but requires you to serve your files over the internet. 2. **Media Library URI**: Use this feature when you need to upload files directly using the `media_library://` protocol. ## Using the Media Library First, create a signed upload URL with the path to your file: ```ts theme={null} const response = await api.request( `/storage/upload/sign/media_library/test.png`, { method: 'POST', headers: { Authorization: `Bearer ${API_KEY}`, }, } ); const url = await response.text(); ``` The file will be uploaded to `test.png`. You can also upload to nested paths, for example `/storage/upload/sign/media_library/my-dir/test.png`. This will create an upload URL for `my-dir/test.png`. Next, upload your file using the signed URL: ```ts theme={null} const res = await fetch(url, { method: 'PUT', body: Buffer.from(BASE_64_IMAGE, 'base64'), headers: { 'Content-Type': 'image/png' }, }); ``` Media library files are automatically deleted after 30 days. Until then, you can use them as often as needed when sending messages or broadcasts by passing them as attachments: * `attachments: ["media_library://test.png"]` * `attachments: ["media_library://my-dir/test.png"]` # Postman Collection Source: https://docs.getmateo.com/resources/postman-collection The Postman Collection for the API. Our Postman Collection is available [here](https://www.postman.com/mateo-crew/workspace/mateo/overview). ``` ``` # Setting up Webhooks Source: https://docs.getmateo.com/webhooks/setting-up-webhooks Automatically trigger HTTP callbacks on events in hellomateo to build custom integrations, notifications, and workflows. With a webhook in hellomateo, you can trigger an HTTP POST callback to a configured URL when a specific event occurs within your hellomateo account. The callback payload will contain useful data related to the event. With this data, webhooks can be used to build custom integrations, notifications, and automate other workflows. * **contact.created**: A new contact has been created. * **contact\_details.updated**: The contact details have been updated. * **contact.deleted**: A contact has been deleted. * **conversation.inbound**: An inbound message has been received. * **conversation.outbound**: A message has been sent. * **conversation.submission\_error**: We are unable to submit the message to the API of the provider. * **conversation.sending\_error**: The provider is unable to send the message to the recipient. * **conversation.tag**: A conversation has been tagged. * **conversation.untag**: A tag has been removed from a conversation. * **conversation.assign**: A conversation has been assigned to a user. * **conversation.unassign**: A conversation has been unassigned from a user. * **conversation.reopen**: A conversation has been reopened. * **conversation.close**: A conversation has been closed. * **form\_submission.completed**: A form submission has been completed. * **form\_submission.aborted**: A form submission has been aborted. For more information about the events you can trigger a webhook with in Hellomateo, including example payloads, see the [webhook event reference](/webhooks/webhook-events-reference) documentation. ### Common webhook use cases There are various scenarios where webhooks can be useful, some of them include: * Building custom chatbots or other workflows * Syncing data back into your ERP or CRM system ### Setting up a webhook in hellomateo Webhooks can be configured in our Web App and via the hellomateo API. Checkout the [Webhook API reference](/api-reference/webhook/post-webhook) for how to create, list, update, and delete webhooks via the API. To create a webhook in the hellomateo Web App: * Go to your Settings > "Integration" > "Webhooks" page. * Click "Create". * Add an unique URL for the webhook to send events to. The URL must: * Use HTTPS. You can use sites like [https://webhook.site](https://webhook.site) or tools like ngrok to create a HTTPS URL to test webhooks locally. * Be reachable from the internet, no local hosts. * Be able to handle incoming HTTP callbacks. * Select the event you want to trigger the webhook for. See the webhook events reference for more information on the events and example response bodies. * Add HTTP headers to the webhook. This is optional, but highly recommended as you can add headers like `Authorization` to secure the webhook. * Click "Save webhook". * On the "Webhooks" page, you can see the status of the last sent webhook under each webhook you set up. ### Handling deliveries There are a few things to remember when receiving a webhook from hellomateo: * You must receive events with an HTTPS server. * Your server must quickly respond with a 2xx successful status code to indicate that the webhook was received successfully. * Any request is retried up to three times. * Hellomateo will not follow any redirects from the server. ### Responding to webhooks quickly To protect your service from being overloaded by webhook deliveries, we recommend responding to the webhook request immediately and handling the processing of the webhook asynchronously. Hellomateo will wait a maximum of 2 seconds for a response from your server before marking the webhook as failed. # Webhook Events Reference Source: https://docs.getmateo.com/webhooks/webhook-events-reference Learn about the webhook events and HTTP responses sent by Hellomateo webhooks. ## Overview Webhooks in hellomateo allow you to trigger an HTTP POST callback to a configured URL when specific events happen within your Hellomateo account. Webhooks can be used to build integrations, such as notifications or workflows. ### `contact.created` A new contact has been created. **Example:** ```json theme={null} { "campaign_messages_this_month": 123, "created_at": "", "description": "", "display_name": "", "email": "", "facebook": "", "full_name": "", "google_business_messaging": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "instagram": "", "latest_marketing_opt_in_request_sent_at": "", "marketing_opt_in": true, "number_of_marketing_opt_in_requests": 123, "organisation_id": "00000000-0000-0000-0000-000000000000", "sms": "", "transactional_opt_in": "legitimate_interest", "updated_at": "", "whatsapp": "" } ``` ### `contact_details.updated` The contact details have been updated. This can be data on the contact itself, its custom field or its marketing subscriptions. **Example:** ```json theme={null} { "campaign_messages_this_month": 123, "created_at": "", "description": "", "display_name": "", "email": "", "facebook": "", "full_name": "", "google_business_messaging": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "instagram": "", "latest_marketing_opt_in_request_sent_at": "", "marketing_opt_in": true, "number_of_marketing_opt_in_requests": 123, "organisation_id": "00000000-0000-0000-0000-000000000000", "sms": "", "transactional_opt_in": "legitimate_interest", "updated_at": "", "whatsapp": "", "my_channel": "accepted", "my_custom_field": "value" } ``` ### `contact.deleted` A contact has been deleted. **Example:** ```json theme={null} { "campaign_messages_this_month": 123, "created_at": "", "description": "", "display_name": "", "email": "", "facebook": "", "full_name": "", "google_business_messaging": "", "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "instagram": "", "latest_marketing_opt_in_request_sent_at": "", "marketing_opt_in": true, "number_of_marketing_opt_in_requests": 123, "organisation_id": "00000000-0000-0000-0000-000000000000", "sms": "", "transactional_opt_in": "legitimate_interest", "updated_at": "", "whatsapp": "" } ``` ### `conversation.inbound` An inbound message has been received. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "inbound", "source": { ... the channel that received the message ... }, "target": { ... the message that was received, including the recipients ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "channel", "target_type": "message", "conversation": { ... the conversation that the message belongs to ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.outbound` A message has been sent. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "inbound", "source": { ... the channel that sent the message ... }, "target": { ... the message that was sent, including the recipients ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "channel", "target_type": "message", "conversation": { ... the conversation that the message belongs to ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.submission_error` We are unable to submit the message to the API of the provider. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "submission_error", "source": { ... the channel that tried to submit the message ... }, "target": { ... the message for which the submission failed, including the recipients ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "channel", "target_type": "message", "conversation": { ... the conversation that the message belongs to ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", "metadata": { ... maybe information about the error ... } } ``` ### `conversation.sending_error` The provider is unable to send the message to the recipient. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "sending_error", "source": { ... the channel that tried to send the message ... }, "target": { ... the message for which sending failed, including the recipients ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "channel", "target_type": "message", "conversation": { ... the conversation that the message belongs to ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", "metadata": { ... maybe information about the error ... } } ``` ### `conversation.tag` A conversation has been tagged. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "tag", "source": { ... the employee or api token that added the tag ... }, "target": { ... the tag that was added ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": "tag", "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.untag` A tag has been removed from a conversation. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "untag", "source": { ... the employee or api token that removed the tag ... }, "target": { ... the tag that was removed ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": "tag", "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.assign` A conversation has been assigned to a user. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "assign", "source": { ... the employee or api token that assigned the employee ... }, "target": { ... the employee that was assigned ... }, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": "employee", "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.unassign` A conversation has been unassigned from a user. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "unassign", "source": { ... the employee or api token that unassigned the employee ... }, "target": null, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": null, "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.reopen` A conversation has been reopened. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "unassign", "source": { ... the employee or api token or rule that reopened the conversation ... }, "target": null, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": null, "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `conversation.close` A conversation has been closed. **Example:** ```json theme={null} { "id": "00000000-0000-0000-0000-000000000000", "type": "unassign", "source": { ... the employee or api token or rule that closed the conversation ... }, "target": null, "inbox_id": "00000000-0000-0000-0000-000000000000", "metadata": null, "created_at": "2024-07-02T15:47:46+00:00", "updated_at": "2024-07-02T15:47:51.613711+00:00", "source_type": "employee", "target_type": null, "conversation": { ... the conversation ... }, "conversation_id": "00000000-0000-0000-0000-000000000000", } ``` ### `form_submission.completed` A form submission has been completed. **Example:** ```json theme={null} { "status": "completed", "form_id": "00000000-0000-0000-0000-000000000000", "contact_id": "00000000-0000-0000-0000-000000000000", "finalised_at": "2024-11-05T14:07:22.612994+00:00", "form_version_id": "00000000-0000-0000-0000-000000000000", "organisation_id": "00000000-0000-0000-0000-000000000000", "duration_seconds": 178, "in_conversation_id": "00000000-0000-0000-0000-000000000000", "contact_external_id": "external-id", "element_submissions": { "field_one": "answer", "field_two": "another answer" } } ``` ### `form_submission.aborted` A form submission has been aborted. **Example:** ```json theme={null} { "status": "aborted", "form_id": "00000000-0000-0000-0000-000000000000", "contact_id": "00000000-0000-0000-0000-000000000000", "finalised_at": "2024-11-05T14:07:22.612994+00:00", "form_version_id": "00000000-0000-0000-0000-000000000000", "organisation_id": "00000000-0000-0000-0000-000000000000", "duration_seconds": 178, "in_conversation_id": "00000000-0000-0000-0000-000000000000", "contact_external_id": "external-id", "element_submissions": { "field_one": "answer", "field_two": null } } ```