Contacts

Scopes: CONTACTS_READ to read, CONTACTS_MANAGE to write, CONTACTS_ERASE to erase. Unmasked names, phones, emails and field values additionally need PII_READ.

contactApi

contactApi(id: ID!): ContactApi

CONTACTS_READ

Reads one contact. Returns null when there is no such contact in the org you are acting on.

Returns ContactApi

contactsApi

contactsApi(filter: ContactApiFilterInput = {}, pagination: ContactApiPaginationInput = {}): ContactApiPage!

CONTACTS_READ

Lists and searches contacts.

Arguments

ContactApiPage returns items, nextCursor and totalCount.

Example

query Contacts {
  contactsApi(filter: { search: "alex" }, pagination: { first: 25 }) {
    items { id displayName phone channels }
    nextCursor
  }
}

Keying Contacts on Your Own ID

If you already have users in your own product, you do not need to store Wexio's contact IDs. Pass your own identifier as externalId and Wexio keys the contact on it.

That gives you two ways to work:

externalId is a stable handle: it survives a contact merge, where Wexio's own peopleId does not. It is also returned on contact reads and writes, so the round trip is closed - you can always map a Wexio contact back to your own user without storing our ids.

upsertContactApi

upsertContactApi(input: ContactApiWriteInput!): ContactApi!

CONTACTS_MANAGE

Creates or updates a contact, idempotently keyed on externalId. Two upserts with the same externalId touch one contact - no duplicate, no need to check first.

Arguments - input: ContactApiWriteInput!

Binding a Channel Identity

channel is the part that prevents duplicates. It attaches a channel identity to the contact before that person ever writes to you, so when a real message arrives from that phone or Telegram ID it resolves to the same contact.

ContactApiChannelInput

Example - import a customer from your own system and pre-bind their WhatsApp number:

mutation Upsert {
  upsertContactApi(input: {
    externalId: "crmco-user-88213"
    displayName: "Alex Moreno"
    phone: "+15551234567"
    language: "en"
    fields: [{ key: "customer_tier", value: "gold" }]
    channel: { kind: WHATSAPP, phone: "+15551234567" }
  }) {
    id
    externalId
    displayName
    channels
  }
}

Run the same mutation again with the same externalId and it updates that contact rather than creating a second one.

contactApiByExternalId

contactApiByExternalId(externalId: String!): ContactApi

CONTACTS_READ

Reads a contact by your identifier. Returns null when no contact carries that externalId.

This is the read that pairs with upsertContactApi - you never have to store Wexio's IDs on your side.

query ByMyId {
  contactApiByExternalId(externalId: "crmco-user-88213") {
    id
    externalId
    displayName
    phone
    channels
  }
}

createContactApi / updateContactApi

createContactApi(input: ContactApiWriteInput!): ContactApi!
updateContactApi(id: ID!, input: ContactApiWriteInput!): ContactApi!

CONTACTS_MANAGE

ContactApiWriteInput

Example

mutation Upsert {
  createContactApi(input: {
    displayName: "Alex Moreno"
    firstName: "Alex"
    lastName: "Moreno"
    phone: "+15551234567"
    language: "en"
    fields: [{ key: "customer_tier", value: "gold" }]
  }) { id displayName }
}

The returned DTO is masked unless the key also holds PII_READ - so a write-only key gets back null for the very values it just set. That is expected.

Custom Fields

Wexio contacts carry custom fields in two layers: a definition (the field itself - name, type, options) and a value per contact.

Definitions

getPeopleFieldDefinitions(filter: PeopleFieldsFilterDto): [PeopleFieldDefinition!]!   # CONTACTS_READ
createPeopleFieldDefinition(input: CreateFieldDefinitionDto!): PeopleFieldDefinition! # CONTACTS_MANAGE
updatePeopleFieldDefinition(id: String!, input: UpdateFieldDefinitionDto!): PeopleFieldDefinition! # CONTACTS_MANAGE
deletePeopleFieldDefinition(id: String!): Boolean!                                    # CONTACTS_MANAGE

Values

getPeopleFieldValues(peopleId: String!, filter: PeopleFieldsFilterDto): [PeopleFieldValue!]!  # CONTACTS_READ
getPeopleFieldValue(id: String!): PeopleFieldValue!                                           # CONTACTS_READ
setPeopleFieldValue(input: SetFieldValueDto!): PeopleFieldValue!                              # CONTACTS_MANAGE
deletePeopleFieldValue(peopleId: String!, fieldId: String!): Boolean!                         # CONTACTS_MANAGE

SetFieldValueDto

Example

mutation SetTier {
  setPeopleFieldValue(input: {
    peopleId: "6804f4d5a6f9f35f6e66f1a2"
    fieldId: "6805c1a0b4d5e6f70123ab45"
    value: "gold"
  }) { _id value }
}

Field values are person PII: a key without PII_READ gets them masked on read, even values it set itself.

Erasure (GDPR)

Erasure is not an update - it destroys a contact and the data attached to it, permanently, to satisfy a right-to-erasure request.

It is gated twice over:

previewErase

previewErase(input: EraseInput!): ErasePreviewType!

CONTACTS_ERASE

A dry run. Changes nothing, and tells you exactly what the real call would destroy.

Arguments - input: EraseInput!

Returns ErasePreviewType!

Example

query Preview {
  previewErase(input: {
    contactId: "6804f4d5a6f9f35f6e66f1c9"
    organisationId: "6716b2f0a1c34d0012ab89ef"
  }) {
    contactId
    willErase { collection count }
    warnings
  }
}

{
  "data": {
    "previewErase": {
      "contactId": "6804f4d5a6f9f35f6e66f1c9",
      "willErase": [
        { "collection": "messages", "count": 412 },
        { "collection": "chats", "count": 3 },
        { "collection": "fieldValues", "count": 11 }
      ],
      "warnings": []
    }
  }
}

eraseContact

eraseContact(input: EraseInput!): EraseResultType!

CONTACTS_ERASE

Performs the erasure. Same input as the preview.

Returns EraseResultType!

Example

mutation Erase {
  eraseContact(input: {
    contactId: "6804f4d5a6f9f35f6e66f1c9"
    organisationId: "6716b2f0a1c34d0012ab89ef"
    reason: "Subject access request #4471"
  }) {
    erasedAt
    erasureLogId
    affectedCounts { collection count }
  }
}

A Safe Erase Flow

1. previewErase - read willErase and warnings.
2. Put the counts in front of a human and get an explicit confirmation.
3. eraseContact with the same contactId and a reason naming your ticket.
4. Record erasureLogId and erasedAt.

Do not skip step 2 in an automated pipeline. An erasure triggered by a bad contact ID cannot be walked back.

Names from WhatsApp

A contact's WhatsApp profile name is used only to fill a gap. It replaces an empty name, or one that is just the phone number - it never overwrites a name set by you or by an operator.

isWhatsAppIdEditable

isWhatsAppIdEditable(peopleId: String!): Boolean!

CONTACTS_READ

Whether this contact's WhatsApp identity can still be changed. Check it before offering an edit - a contact with live WhatsApp history is locked.

A Note on IDs

Two different identifiers appear here, and mixing them is the easiest mistake to make:

Webhook payloads also carry contactId - the merge-winner ID. Key your own records on that if you want contact merges to reconcile cleanly.