Contact

Create, update, or retrieve a contact

Retrieves OR creates and possibly updates a contact by name or phone number.

If a phone number is provided, by default, Telerivet will search for an existing contact with that phone number (including suffix matches to allow finding contacts with phone numbers in a different format). If a phone number is not provided but a name is provided, Telerivet will search for a contact with that exact name (case insensitive). This behavior can be modified by setting the lookup_key parameter to look up a contact by another field, including a custom variable.

If no existing contact is found, a new contact will be created.

Then that contact will be updated with any parameters provided (name, phone_number, vars, default_route_id, send_blocked, add_group_ids, remove_group_ids).

post/v1/projects/{project_id}/contacts

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/contacts
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://telerivet.com/oauth/authorize, token URL https://api.telerivet.com/oauth/token)

Path parameters

project_idstring required

ID of the Project

Request body

namestring

Name of the contact

phone_numberstring

Phone number of the contact

lookup_key'phone_number' | 'name' | 'id' | 'vars.variable_name' | 'none'

The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.

send_blockedboolean

True if Telerivet is blocked from sending messages to this contact

default_route_idstring

ID of the route to use by default to send messages to this contact

add_group_idsstring

ID of one or more groups to add this contact as a member (max 20)

idstring

ID of an existing contact (only used if lookup_key is 'id')

remove_group_idsstring

ID of one or more groups to remove this contact as a member (max 20)

varsobject

Custom variables and values to update on the contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Example request

{
  "name": "John Smith",
  "phone_number": "5550123"
}

Response

Successful response

idstring

ID of the contact

namestring

Name of the contact

phone_numberstring

Phone number of the contact

time_createdinteger

Time the contact was added in Telerivet

time_updatedinteger

Time the contact was last updated in Telerivet

send_blockedboolean

True if Telerivet is blocked from sending messages to this contact

conversation_status'closed' | 'active' | 'handled'

Current status of the conversation with this contact

last_message_timeinteger nullable

Last time the contact sent or received a message (null if no messages have been sent or received)

last_incoming_message_timeinteger nullable

Last time a message was received from this contact

last_outgoing_message_timeinteger nullable

Last time a message was sent to this contact

message_countinteger

Total number of non-deleted messages sent to or received from this contact

incoming_message_countinteger

Number of messages received from this contact

outgoing_message_countinteger

Number of messages sent to this contact

last_message_idstring

ID of the last message sent to or received from this contact (null if no messages have been sent or received)

default_route_idstring

ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route)

group_idsstring[]

List of IDs of groups that this contact belongs to

varsobject

Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

project_idstring

ID of the project this contact belongs to

urlstring

URL to this contact in the Telerivet web app

Example response

{
  "id": "CTa1299c3d0e371023",
  "name": "John Smith",
  "phone_number": "+16505550123",
  "time_created": 1390348075,
  "time_updated": 1390348099,
  "conversation_status": "active",
  "last_message_time": 1395881121,
  "last_incoming_message_time": 1395881121,
  "last_outgoing_message_time": 1395881032,
  "message_count": 13,
  "incoming_message_count": 2,
  "outgoing_message_count": 11,
  "last_message_id": "SM97f47ac232df154d",
  "project_id": "PJ2ad0100821a98bea",
  "url": "https://telerivet.com/p/asdf/contact/CTa1299c3d0e371023"
}

Changes

No recorded changes to this operation across all 1 revision of this API.