Update a contact profile

Change a contact profile's Agent, line, template, texts, contact hours, name or metadata. Omitted fields stay and null clears one. The channel type never changes: a field of the other type fails with CHANNEL_TYPE_MISMATCH. Conversations already started keep what they started with.

Scope: raiz:profiles:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; idempotent, safe to retry
Limits: request body up to 32 KB, response up to 1 MB
CLI: arbol raiz profiles update · MCP tool: raiz_profiles_update

PATCH

https://api.getarbol.com/v1/raiz/profiles/{profileId}

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope raiz:profiles:write. Get an API key.

Path parameters

profileId
string
required
Communication profile id.

pattern: ^prf_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$

Request body JSON required

agentId
optional
string
Agent id.

pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
channelId
optional
string | null
The line to contact from, of the profile's channel type. Null: the Agent's own channel; for calls, then the platform's shared line.

pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
contactHours
optional
array of
object
When a conversation may start, in the profile's time zone. Empty: any time. Outside them createConversation fails with OUTSIDE_CONTACT_HOURS and nothing is sent.
- days
  array of
  MO
  or
  TU
  or
  WE
  or
  TH
  or
  FR
  or
  SA
  +1 more
  required
- from
  string
  required
  Local start time, HH:MM, inclusive.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
- to
  string
  required
  Local end time, HH:MM, exclusive (24:00 for midnight).
  
  pattern: ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$
}
expectedVersion
optional
integer
The version you read. When present, the change applies only if nobody changed the resource since; otherwise it fails with VERSION_CONFLICT.

minimum: 1
firstMessage
optional
string | null
What the Agent says first on every call, instead of its own first message. May reference request variables as {{name}}.

maxLength: 2000 · minLength: 1
instructions
optional
string | null
What these calls are about, added to the Agent's instructions on every call. May reference request variables as {{name}}.

maxLength: 8000 · minLength: 1
metadata
optional
object
Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
name
optional
string
What the profile is for, as people read it.

maxLength: 200 · minLength: 1
template
optional
object
The approved template that opens every conversation. WhatsApp allows a business to start a conversation only with one.
- language
  string
  required
  The template's language: WhatsApp's code (es, es_MX) or a BCP 47 tag (es-MX).
  
  maxLength: 15 · minLength: 2
- name
  string
  required
  An approved template of the channel's WhatsApp Business Account. Its body may have variables; header media and button parameters are not supported.
  
  maxLength: 512 · minLength: 1
- parameters
  optional
  array of
  string
  The template's body parameters, in order. Each is a text that may reference the request's variables as {{name}}, for example {{patient_name}} or Dr. {{doctor}}.
  
  maxLength: 1024
}
timeZone
optional
string | null
IANA time zone of the contact hours. Null: the organization's.

maxLength: 64 · pattern: ^[A-Za-z]+(/[A-Za-z0-9_+-]+)*$

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- agentId
  string
  required
  Agent id.
  
  pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- agentName
  string
  required
- channelId
  string | null
  required
  The channel the profile names; null to use its Agent's (see line).
  
  pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- channelType
  voice
  or
  whatsapp
  required
  How the profile contacts: a call with a voice Agent (voice), or a WhatsApp conversation opened with an approved template and held by a text Agent (whatsapp). Fixed at creation.
- contactHours
  array of
  object
  required
  When a conversation may start, in the profile's time zone. Empty: any time. Outside them createConversation fails with OUTSIDE_CONTACT_HOURS and nothing is sent.
  
  days
  array of
  MO
  or
  TU
  or
  WE
  or
  TH
  or
  FR
  or
  SA
  +1 more
  required
  from
  string
  required
  Local start time, HH:MM, inclusive.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  to
  string
  required
  Local end time, HH:MM, exclusive (24:00 for midnight).
  
  pattern: ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$
- createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- firstMessage
  string | null
  required
  What the Agent says first on every call, instead of its own first message. May reference request variables as {{name}}.
  
  maxLength: 2000 · minLength: 1
- id
  string
  required
  Communication profile id.
  
  pattern: ^prf_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- instructions
  string | null
  required
  What these calls are about, added to the Agent's instructions on every call. May reference request variables as {{name}}.
  
  maxLength: 8000 · minLength: 1
- line
  object | null
  required
  The line conversations start from: the profile's own channel, or for WhatsApp its Agent's oldest line that can send. Null for a voice profile without a channel (each call uses the Agent's own line, else the managed line) or when no line can send.
  
  address
  string | null
  required
  The number, in E.164 form.
  
  id
  string
  required
  The line to contact from, of the profile's channel type. Null: the Agent's own channel; for calls, then the platform's shared line.
  
  pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  name
  string | null
  required
- metadata
  object
  required
  Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
- name
  string
  required
- template
  object | null
  required
  WhatsApp profiles only.
  
  language
  string
  required
  The template's language: WhatsApp's code (es, es_MX) or a BCP 47 tag (es-MX).
  
  maxLength: 15 · minLength: 2
  name
  string
  required
  An approved template of the channel's WhatsApp Business Account. Its body may have variables; header media and button parameters are not supported.
  
  maxLength: 512 · minLength: 1
  parameters
  array of
  string
  required
  The template's body parameters, in order. Each is a text that may reference the request's variables as {{name}}, for example {{patient_name}} or Dr. {{doctor}}.
  
  maxLength: 1024
- timeZone
  string | null
  required
  IANA time zone of the contact hours. Null: the organization's.
  
  maxLength: 64 · pattern: ^[A-Za-z]+(/[A-Za-z0-9_+-]+)*$
- updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- version
  integer
  required
  minimum: 1
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

409

CHANNEL_TYPE_MISMATCH: This operation or field does not apply to this channel's type.
VERSION_CONFLICT: The resource changed after it was read. Read it again and retry with the new version.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

422

TIME_ZONE_UNKNOWN: The time zone is not in the IANA time zone database.
CHANNEL_AGENT_MISMATCH: This Agent cannot serve this channel: voice channels need a voice Agent; WhatsApp and web channels need a text Agent.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}