Kolumna telefonu przechowuje numer telefonu razem z kodem kraju. Może też wyświetlać flagę kraju obok numeru.

Za pomocą API kolumna telefonu obsługuje odczyt, filtrowanie, aktualizowanie i czyszczenie wartości.

Typ kolumny	Typ implementacji	Obsługiwane operacje
phone	PhoneValue	Odczyt: tak Filtrowanie: tak Aktualizowanie: tak Czyszczenie: tak

---

Zapytania

Kolumny telefonu możesz odpytywać za pomocą pola column_values obiektu items, używając fragmentu inline dla typu PhoneValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on PhoneValue {
        id
        phone
        country_short_name
        text
        value
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on PhoneValue {
          id
          phone
          country_short_name
          text
          value
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

const response = await mondayApiClient.request(query, variables);

Pola

Możesz użyć poniższych pól, aby określić, jakie informacje zwróci implementacja PhoneValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
country_short_name String	Kod kraju ISO-2 (np. "US", "GB"). Zwraca null, jeśli kolumna jest pusta.
id ID!	Unikalny identyfikator kolumny.
phone String	Numer telefonu zapisany w kolumnie. Zwraca null, jeśli kolumna jest pusta.
text String	Wartość kolumny w postaci tekstu. Zwraca "", jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny.
updated_at Date	Data ostatniej aktualizacji kolumny.
value JSON	Surowa wartość kolumny w postaci ciągu JSON. Zwraca {"phone": "+12025550169", "countryShortName": "US"}.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Alice Johnson",
        "column_values": [
          {
            "id": "phone",
            "phone": "+12025550169",
            "country_short_name": "US",
            "text": "+12025550169",
            "value": "{\"phone\":\"+12025550169\",\"countryShortName\":\"US\"}",
            "updated_at": "2026-03-20T12:00:00Z"
          }
        ]
      },
      {
        "name": "Bob Smith",
        "column_values": [
          {
            "id": "phone",
            "phone": null,
            "country_short_name": null,
            "text": "",
            "value": null,
            "updated_at": null
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

Możesz filtrować elementy według wartości numeru telefonu za pomocą obiektu items_page. Kolumna telefonu obsługuje filtrowanie według kodu kraju, tekstu numeru telefonu oraz pustych wartości.

Operator	Wartość porównawcza	Opis
any_of	Tablica kodów krajów ISO-2 (np. ["US"])	Zwraca elementy, których kod kraju numeru telefonu jest zgodny z dowolnym z podanych kodów.
not_any_of	Tablica kodów krajów ISO-2 (np. ["US"])	Pomija elementy, których kod kraju numeru telefonu jest zgodny z dowolnym z podanych kodów.
contains_text	Fragment lub cały numer telefonu w postaci tekstu (np. "2025")	Zwraca elementy, których numer telefonu zawiera podany tekst.
not_contains_text	Fragment lub cały numer telefonu w postaci tekstu (np. "2025")	Pomija elementy, których numer telefonu zawiera podany tekst.
is_empty	[]	Zwraca elementy, w których wartość numeru telefonu jest pusta (nieustawiona).
is_not_empty	[]	Zwraca elementy, w których ustawiono wartość numeru telefonu.

Przykłady

Filtrowanie według kodu kraju

Ten przykład zwraca wszystkie elementy z numerem telefonu ze Stanów Zjednoczonych.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "phone"
            compare_value: ["US"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on PhoneValue {
            phone
            country_short_name
          }
        }
      }
    }
  }
}

Filtrowanie według tekstu numeru telefonu

Ten przykład zwraca wszystkie elementy, których numer telefonu zawiera tekst „2025”.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "phone"
            compare_value: "2025"
            operator: contains_text
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on PhoneValue {
            phone
          }
        }
      }
    }
  }
}

Filtrowanie według pustego numeru telefonu

Ten przykład zwraca wszystkie elementy na wskazanej tablicy, w których wartość numeru telefonu jest pusta.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "phone"
            compare_value: []
            operator: is_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

---

Mutacje

Aktualizowanie

Możesz zaktualizować kolumnę telefonu za pomocą change_simple_column_value lub change_multiple_column_values. W zależności od wybranej mutacji możesz przesłać wartości jako zwykłe ciągi tekstowe lub obiekty JSON.

change_simple_column_value

Prześlij wartości w polu value w poniższym formacie:

"+<phone number> <ISO-2 country code>"

Zapisz kod kraju wielkimi literami i oddziel go od numeru spacją.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "phone"
    value: "+12025550169 US"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnId: String!, $value: String!) {
    change_simple_column_value(
      item_id: $itemId
      board_id: $boardId
      column_id: $columnId
      value: $value
    ) {
      id
    }
  }
`;

const variables = {
  boardId: "1234567890",
  itemId: "9876543210",
  columnId: "phone",
  value: "+12025550169 US"
};

const response = await mondayApiClient.request(query, variables);

change_multiple_column_values

Prześlij klucze phone i countryShortName jako obiekt JSON w polu column_values. Użyj wielkich liter w kodzie kraju ISO-2.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"phone\": {\"phone\": \"+12025550169\", \"countryShortName\": \"US\"}}"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: "1234567890",
  itemId: "9876543210",
  columnValues: JSON.stringify({
    phone: { phone: "+12025550169", countryShortName: "US" }
  })
};

const response = await mondayApiClient.request(query, variables);

Weryfikacja numeru telefonu

Numery telefonów muszą spełniać zasady prawidłowego zapisu krajowego dla wskazanego kodu kraju.

Kolumna telefonu korzysta z:

• standardu ISO 3166 w przypadku kodów krajów,
• biblioteki Google libphonenumber do weryfikacji numerów.

Jeśli pojawią się błędy weryfikacji, możesz sprawdzić numer za pomocą narzędzia online.

Akceptowane formaty

Kraj	Akceptowane formaty
Stany Zjednoczone (US)	"{\"phone\":\"+12025550172\",\"countryShortName\":\"US\"}" "{\"phone\":\"12025550172\",\"countryShortName\":\"US\"}" "{\"phone\":\"2025550169\",\"countryShortName\":\"US\"}"
Wielka Brytania (GB)	"{\"phone\":\"+447975777666\",\"countryShortName\":\"GB\"}" "{\"phone\":\"447975777666\",\"countryShortName\":\"GB\"}" "{\"phone\":\"+442079460990\",\"countryShortName\":\"GB\"}" "{\"phone\":\"07975777666\",\"countryShortName\":\"GB\"}"
Australia (AU)	"{\"phone\":\"+61488870510\",\"countryShortName\":\"AU\"}" "{\"phone\":\"61488870510\",\"countryShortName\":\"AU\"}" "{\"phone\":\"0488870510\",\"countryShortName\":\"AU\"}" "{\"phone\":\"0255504321\",\"countryShortName\":\"AU\"}"

Ustawianie numeru telefonu podczas tworzenia elementu

Możesz ustawić wartość numeru telefonu podczas tworzenia elementu, przekazując ją w argumencie column_values.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New contact"
    column_values: "{\"phone\": {\"phone\": \"+12025550169\", \"countryShortName\": \"US\"}}"
  ) {
    id
    name
  }
}

Czyszczenie

Możesz wyczyścić kolumnę telefonu za pomocą change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż pusty ciąg w polu value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "phone"
    value: ""
  ) {
    id
  }
}

change_multiple_column_values

Przekaż null w polu column_values.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"phone\": null}"
  ) {
    id
  }
}

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić ustawienia kolumny telefonu, możesz pobrać jej konfigurację za pomocą pola settings.

query {
  boards(ids: 1234567890) {
    columns(ids: ["phone"]) {
      id
      title
      settings
    }
  }
}

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON. W przypadku kolumn telefonu z ustawieniami domyślnymi jego wartością jest {}. Mogą w nim występować następujące klucze:

Klucz	Typ	Opis
show_flag	boolean	Określa, czy obok numeru telefonu ma być wyświetlana flaga kraju.

Przykładowa odpowiedź settings

{}

---

Pobieranie schematu typu kolumny

Schemat JSON ustawień kolumny telefonu możesz pobrać programowo za pomocą zapytania get_column_type_schema. Zwraca ono strukturę, reguły weryfikacji i dostępne właściwości konfiguracji kolumny.

query {
  get_column_type_schema(
    type: phone
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {
              "show_flag": {
                "type": "boolean",
                "description": "Whether to display the country flag next to the phone number"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

Odpowiedź zawiera nazwy właściwości, ich typy, ograniczenia (takie jak maksymalna długość i dozwolone wartości) oraz opisy poszczególnych ustawień. Możesz użyć tych danych do weryfikacji ustawień kolumny, dynamicznego generowania interfejsów lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.